dotnet / dotnet/dotnet-api-docs

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

Open
#4,968 0 comments 1 reaction 0 assignees View on GitHub
area-System.Buffers doc-enhancement Pri3
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.