Documentation request: Improve option descriptions.

[beruic]

I'm converting an app from using cordova-plugin-file to using the Capacitor API. This plugin is a big help here (and should be a part of the official plugin IMHO), but I wonder if i am doing it right.

I am not sure I understand the point of the fallback: option. What I think it does is the following:

• The default is true, so by default all errors will cause fall back to trying Filesystem.writeFile() instead.
• If fallback: is defined to be a function, that function is expected to take an error, and return a boolean, which i turn decides whether it should fall backs to Filesystem.writeFile() afterwards.
• If fallback: is set to false or the set function returns false, the promise will reject with the error.
• Filesystem.writeFile() fallback failing will result in the promise rejecting with an error.

Is this correct?

Also, how does the fallback to Filesystem.writeFile() work?

[diachedelic]

That is correct. The reason there is a fallback option is that sometimes the BlobWriter server is inexplicably not running or not contactable.

When running the fallback, the blob is sliced into chunks, each of which is Base64 encoded and appended to an empty file. This helps avoid exhausting available memory if the file is large. You can read the source here.

I apologise for the poor documentation.

[beruic]

I have made a PR with a quick adaption of my description integrated in the README.

BTW, can't you make it kickstart the server instead before uploading, when it's detected that it is not running?

[diachedelic]

@beruic Thanks. I haven't tried a "kickstart" approach because I do not yet fully understand why the server is sometimes down. My guess is it has something to do with the app transitioning to a background state, in which case a kickstart would not successfully start the server. Can you provide any insights?

[beruic]

@diachedelic Sorry no. I only have an abstract view of this. Not much practical Android or iOS experience :) As far as I know any plugin can send text messages through the usual Capacitor API. If the server can be started this way, I guess you could both keep it dormant until needed, and try to start it before resolving to fallback.