docs: Better document writing binary data

[OS-pedrogustavobilro]

To address #40

@alextreppass / @kzKallisti / @HarelM feel free to leave feedback!

[HarelM]

This looks good, thanks! I would consider addind a base64 encoding option to explicitly say "hey I'm passing a base64 string", right now you have to pass "undefined" (or omit encoding) if you pass a base64 string. You might consider also adding something like:
If the provided content is not a base64 string this will throw an error, although this might be implied anyway.

[OS-pedrogustavobilro]

I would consider adding a base64 encoding option

Hmm I suppose so, right now it's just character encodings for text data. We may do that in a future PR.

If the provided content is not a base64 string this will throw an error.

I can make that a bit more explicit in this PR yeah.

[kzKallisti]

hi @OS-pedrogustavobilro! Just saw this in my email. Quick question, am I understanding this correctly that if I simply pass a base64 string and no encoding the write actually "just works"? Never thought to try that 🤔

would that mean then that my example is double-encoding the file?

[OS-pedrogustavobilro]

Hey @kzKallisti, per your example, if you specify Encoding.UTF8 to writeFile, it will write the base64 data as a string; if you don't pass an encoding it will decode the base64 data and write as binary. Similarly, if you pass Encoding.UTF8 to readFile, it will try to return a textual representation of the file (even if it is binary file); if you don't pass an encoding, it will base64-encode the binary data and return it to you.

The encoding parameter doc is where the confusing probably was, as prior to this PR it didn't properly specify what happened if you didn't pass an encoding.

Hope that helps!