Document Base64Url character encoding details in API reference (#11470)

* Initial plan for issue

* Add Base64Url character documentation explaining URL-safe encoding

Co-authored-by: jeffhandley <[email protected]>

* Fix Base64Url capitalization inconsistency in documentation

Co-authored-by: gewarren <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: jeffhandley <[email protected]>
Co-authored-by: gewarren <[email protected]>

Author: 3 people

xml/System.Buffers.Text/Base64Url.xml

@@ -27,7 +27,7 @@
   <Interfaces />
   <Docs>
     <summary>Converts between binary data and URL-safe ASCII encoded text that's represented in Base64Url characters.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>Base64Url encoding uses the same alphabet as standard Base64 encoding, except that the characters '+' and '/' are replaced with '-' and '_' respectively to make the output URL-safe.</remarks>
   </Docs>
   <Members>
     <Member MemberName="DecodeFromChars">
@@ -373,7 +373,7 @@
         <param name="source">The input span which contains binary data that needs to be encoded.</param>
         <summary>Encodes the span of binary data into unicode ASCII chars represented as Base64Url.</summary>
         <returns>A char array which contains the result of the operation, i.e. the ASCII chars in Base64Url.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
       </Docs>
     </Member>
     <Member MemberName="EncodeToChars">
@@ -406,7 +406,7 @@
         <param name="destination">The output span which contains the result of the operation, i.e. the ASCII chars in Base64Url.</param>
         <summary>Encodes the span of binary data into Unicode ASCII chars represented as Base64Url.</summary>
         <returns>The number of bytes written into the destination span. This can be used to slice the output for subsequent calls, if necessary.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
         <exception cref="T:System.ArgumentException">The buffer in <paramref name="destination" /> is too small to hold the encoded output.</exception>
       </Docs>
     </Member>
@@ -449,7 +449,7 @@
         </param>
         <summary>Encodes the span of binary data into unicode ASCII chars represented as Base64Url.</summary>
         <returns>One of the enumeration values that indicates the success or failure of the operation.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
       </Docs>
     </Member>
     <Member MemberName="EncodeToString">
@@ -486,7 +486,7 @@
         <param name="source">The input span that contains binary data that needs to be encoded.</param>
         <summary>Encodes the span of binary data into Unicode string represented as Base64Url ASCII chars.</summary>
         <returns>A string that contains the result of the operation, i.e. the ASCII string in Base64Url.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
       </Docs>
     </Member>
     <Member MemberName="EncodeToUtf8">
@@ -523,7 +523,7 @@
         <param name="source">The input span which contains binary data that needs to be encoded.</param>
         <summary>Encodes the span of binary data into UTF-8 encoded text represented as Base64Url.</summary>
         <returns>The output byte array which contains the result of the operation, i.e. the UTF-8 encoded text in Base64Url.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
       </Docs>
     </Member>
     <Member MemberName="EncodeToUtf8">
@@ -556,7 +556,7 @@
         <param name="destination">The output span which contains the result of the operation, i.e. the UTF-8 encoded text in Base64Url.</param>
         <summary>Encodes the span of binary data into UTF-8 encoded text represented as Base64Url.</summary>
         <returns>The number of bytes written into the destination span. This can be used to slice the output for subsequent calls, if necessary.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
         <exception cref="T:System.ArgumentException">The buffer in <paramref name="destination" /> is too small to hold the encoded output.</exception>
       </Docs>
     </Member>
@@ -599,7 +599,7 @@
         </param>
         <summary>Encodes the span of binary data into UTF-8 encoded text represented as Base64Url.</summary>
         <returns>One of the enumeration values that indicates the success or failure of the operation.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
       </Docs>
     </Member>
     <Member MemberName="GetEncodedLength">
@@ -926,7 +926,7 @@
         <summary>Encodes the span of binary data into Unicode ASCII chars represented as Base64Url.</summary>
         <returns>
           <see langword="true" /> if chars encoded successfully; <see langword="false" /> if <paramref name="destination" /> is too small.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
       </Docs>
     </Member>
     <Member MemberName="TryEncodeToUtf8">
@@ -962,7 +962,7 @@
         <summary>Encodes the span of binary data into UTF-8 encoded chars represented as Base64Url.</summary>
         <returns>
           <see langword="true" /> if bytes encoded successfully; <see langword="false" /> if <paramref name="destination" /> is too small.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
       </Docs>
     </Member>
     <Member MemberName="TryEncodeToUtf8InPlace">
@@ -1007,7 +1007,7 @@
         </summary>
         <returns>
           <see langword="true" /> if bytes encoded successfully; <see langword="false" /> if <paramref name="buffer" /> is too small to fit the result.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
       </Docs>
     </Member>
   </Members>