dotnet / dotnet/dotnet-api-docs
Recommend clarifying some of the System.Buffers.Text.Base64 docs
- Dominant language
- C#
- Stars
- 949
- Forks
- 1.7k
- Avg merge
- 3d 27m
- Merged PRs (30d)
- 49
Description
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`](https://docs.microsoft.com/dotnet/api/system.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`](https://docs.microsoft.com/dotnet/api/system.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.
Contributor guide
Assessment
This issue has not been assessed yet.