Recommend clarifying some of the System.Buffers.Text.Base64 docs

[GrabYourPitchforks]

We should clarify some of the docs under the System.Buffers.Text.Base64 class. Here are some suggested clarifications.

Base64.EncodeToUtf8

https://docs.microsoft.com/dotnet/api/system.buffers.text.base64.encodetoutf8

In the Remarks section, we should clarify the relationship between the different parameters. I'd suggest wording as follows.

If isFinalBlock is true, this method will pad the destination buffer with as many '=' characters as necessary to create well-formed base64 output. Padding bytes are not added if isFinalBlock is false.

• OperationStatus.Done - All of the source buffer bytes were successfully encoded as base64 into the destination buffer. If isFinalBlock is true, any required '=' padding characters were also successfully appended to the destination buffer.

• OperationStatus.DestinationTooSmall - The destination buffer is not large enough to fit the base64-encoded representation of the source buffer.

• OperationStatus.NeedMoreData - The caller specified isFinalBlock as false, and the input buffer length is not a multiple of 3 bytes.

This method has undefined behavior when the bytes (source) and utf8 (destination) buffers overlap. Callers can use the MemoryExtensions.Overlaps extension method to detect this condition if necessary.

Base64.EncodeToUtf8InPlace

https://docs.microsoft.com/dotnet/api/system.buffers.text.base64.encodetoutf8inplace

In the Remarks section, we should clarify that the method is one-shot.

This method will pad the buffer with as many '=' characters as necessary to create well-formed base64 output.

• OperationStatus.DestinationTooSmall - There isn't enough space in the buffer beyond dataLength to fit the result of encoding the input. The contents of the buffer will remain unmodified and bytesWritten will be set to 0.

Base64.DecodeFromUtf8

https://docs.microsoft.com/dotnet/api/system.buffers.text.base64.decodefromutf8

In the Remarks section, we should clarify the relationship between the different parameters. I'd suggest wording as follows.

• OperationStatus.Done - All of the source buffer bytes were successfully decoded from base64 into the destination buffer. If isFinalBlock is true, any required '=' padding characters were also successfully validated.

• OperationStatus.DestinationTooSmall - The destination buffer is not large enough to fit the base64-decoded representation of the source buffer.

• OperationStatus.NeedMoreData - The caller specified isFinalBlock as false, and the input buffer length is not a multiple of 4 bytes.

• OperationStatus.InvalidData - The source buffer contained invalid base64 data. This can be caused by a non-base64 character (such as '*' or whitespace) appearing in the source buffer. If isFinalBlock is true, this can also be caused by the source buffer having incomplete or invalid padding.

This method has undefined behavior when the utf8 (source) and bytes (destination) buffers overlap. Callers can use the MemoryExtensions.Overlaps extension method to detect this condition if necessary.

Base64.DecodeFromUtf8InPlace

https://docs.microsoft.com/dotnet/api/system.buffers.text.base64.decodefromutf8inplace

In the Remarks section, we should clarify that the method is one-shot.

This method requires the source buffer to contain only well-formed base64 data, including any necessary '=' padding characters.

• OperationStatus.InvalidData - The source buffer contained invalid base64 data. This can be caused by a non-base64 character (such as '*' or whitespace) appearing in the source buffer. It can also be caused by the source buffer having incomplete or invalid padding.