Backport of CBOR documentation (#49506)

* initial backport of CBOR documentation * apply manual fixups to documentation * Update src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Map.cs Co-authored-by: Carlos Sanchez <[email protected]> * Update src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Map.cs Co-authored-by: Carlos Sanchez <[email protected]> Co-authored-by: Carlos Sanchez <[email protected]>
dotnet · Apr 19, 2021 · 2aba0c5 · 2aba0c5
1 parent 01a8a5c
commit 2aba0c5
Show file tree

Hide file tree

Showing 20 changed files with 627 additions and 1,068 deletions.
diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborConformanceLevel.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborConformanceLevel.cs
@@ -7,48 +7,44 @@
 
 namespace System.Formats.Cbor
 {
-    /// <summary>
-    ///   Defines supported conformance modes for encoding and decoding CBOR data.
-    /// </summary>
+    /// <summary>Defines supported conformance modes for encoding and decoding CBOR data.</summary>
     public enum CborConformanceMode
     {
-        /// <summary>
-        ///   Ensures that the CBOR data is well-formed, as specified in RFC7049.
-        /// </summary>
+        /// <summary>Ensures that the CBOR data is well-formed, as specified in RFC7049.</summary>
         Lax,
 
         /// <summary>
-        ///   Ensures that the CBOR data adheres to strict mode, as specified in RFC7049 section 3.10.
-        ///   Extends lax conformance with the following requirements:
-        ///   <list type="bullet">
-        ///   <item>Maps (major type 5) must not contain duplicate keys.</item>
-        ///   <item>Simple values (major type 7) must be encoded as small a possible and exclude the reserved values 24-31.</item>
-        ///   <item>UTF-8 string encodings must be valid.</item>
-        ///   </list>
+        /// <para>Ensures that the CBOR data adheres to strict mode, as specified in RFC7049 section 3.10.</para>
+        /// <para>Extends lax conformance with the following requirements:</para>
+        /// <list type="bullet">
+        /// <item>Maps (major type 5) must not contain duplicate keys.</item>
+        /// <item>Simple values (major type 7) must be encoded as small a possible and exclude the reserved values 24-31.</item>
+        /// <item>UTF-8 string encodings must be valid.</item>
+        /// </list>
         /// </summary>
         Strict,
 
         /// <summary>
-        ///   Ensures that the CBOR data is canonical, as specified in RFC7049 section 3.9.
-        ///   Extends strict conformance with the following requirements:
-        ///   <list type="bullet">
-        ///   <item>Integers must be encoded as small as possible.</item>
-        ///   <item>Maps (major type 5) must contain keys sorted by encoding.</item>
-        ///   <item>Indefinite-length items must be made into definite-length items.</item>
-        ///   </list>
+        /// <para>Ensures that the CBOR data is canonical, as specified in RFC7049 section 3.9.</para>
+        /// <para>Extends strict conformance with the following requirements:</para>
+        /// <list type="bullet">
+        /// <item>Integers must be encoded as small as possible.</item>
+        /// <item>Maps (major type 5) must contain keys sorted by encoding.</item>
+        /// <item>Indefinite-length items must be made into definite-length items.</item>
+        /// </list>
         /// </summary>
         Canonical,
 
         /// <summary>
-        ///   Ensures that the CBOR data is canonical, as specified by the CTAP v2.0 standard, section 6.
-        ///   Extends strict conformance with the following requirements:
-        ///   <list type="bullet">
-        ///   <item>Maps (major type 5) must contain keys sorted by encoding.</item>
-        ///   <item>Indefinite-length items must be made into definite-length items.</item>
-        ///   <item>Integers must be encoded as small as possible.</item>
-        ///   <item>The representations of any floating-point values are not changed.</item>
-        ///   <item>CBOR tags (major type 6) are not permitted.</item>
-        ///   </list>
+        /// <para>Ensures that the CBOR data is canonical, as specified by the CTAP v2.0 standard, section 6.</para>
+        /// <para>Extends strict conformance with the following requirements:</para>
+        /// <list type="bullet">
+        /// <item>Maps (major type 5) must contain keys sorted by encoding.</item>
+        /// <item>Indefinite-length items must be made into definite-length items.</item>
+        /// <item>Integers must be encoded as small as possible.</item>
+        /// <item>The representations of any floating-point values are not changed.</item>
+        /// <item>CBOR tags (major type 6) are not permitted.</item>
+        /// </list>
         /// </summary>
         Ctap2Canonical,
     }

diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborContentException.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborContentException.cs
@@ -5,14 +5,12 @@
 
 namespace System.Formats.Cbor
 {
-    /// <summary>
-    ///   The exception that is thrown when a CBOR encoding is invalid.
-    /// </summary>
+    /// <summary>The exception that's thrown when CBOR data is invalid.</summary>
     [Serializable]
     public class CborContentException : Exception
     {
         /// <summary>
-        ///  Initializes a new instance of the <see cref="System.Formats.Cbor.CborContentException" /> class, using the provided message.
+        ///  Initializes a new instance of the <see cref="CborContentException" /> class, using the provided message.
         /// </summary>
         /// <param name="message">The error message that explains the reason for the exception.</param>
         public CborContentException(string? message)
@@ -22,7 +20,7 @@ public CborContentException(string? message)
         }
 
         /// <summary>
-        ///  Initializes a new instance of the <see cref="System.Formats.Cbor.CborContentException" /> class,
+        ///  Initializes a new instance of the <see cref="CborContentException" /> class,
         ///  using the provided message and exception that is the cause of this exception.
         /// </summary>
         /// <param name="message">The error message that explains the reason for the exception.</param>
@@ -34,7 +32,7 @@ public CborContentException(string? message, Exception? inner)
         }
 
         /// <summary>
-        ///   Initializes a new instance of the <see cref="System.Formats.Cbor.CborContentException" /> class with serialized data.
+        ///   Initializes a new instance of the <see cref="CborContentException" /> class with serialized data.
         /// </summary>
         /// <param name="info">The object that holds the serialized object data.</param>
         /// <param name="context">The contextual information about the source or destination.</param>

diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborTag.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborTag.cs
@@ -3,117 +3,72 @@
 
 namespace System.Formats.Cbor
 {
-    /// <summary>
-    ///   Represents a CBOR semantic tag (major type 6).
-    /// </summary>
+    /// <summary>Represents a CBOR semantic tag (major type 6).</summary>
     [CLSCompliant(false)]
     public enum CborTag : ulong
     {
-        /// <summary>
-        ///   Tag value for RFC3339 date/time strings.
-        /// </summary>
+        /// <summary>Tag value for RFC3339 date/time strings.</summary>
         DateTimeString = 0,
 
-        /// <summary>
-        ///   Tag value for Epoch-based date/time strings.
-        /// </summary>
+        /// <summary>Tag value for Epoch-based date/time strings.</summary>
         UnixTimeSeconds = 1,
 
-        /// <summary>
-        ///   Tag value for unsigned bignum encodings.
-        /// </summary>
+        /// <summary>Tag value for unsigned bignum encodings.</summary>
         UnsignedBigNum = 2,
 
-        /// <summary>
-        ///   Tag value for negative bignum encodings.
-        /// </summary>
+        /// <summary>Tag value for negative bignum encodings.</summary>
         NegativeBigNum = 3,
 
-        /// <summary>
-        ///   Tag value for decimal fraction encodings.
-        /// </summary>
+        /// <summary>Tag value for decimal fraction encodings.</summary>
         DecimalFraction = 4,
 
-        /// <summary>
-        ///   Tag value for big float encodings.
-        /// </summary>
+        /// <summary>Tag value for big float encodings.</summary>
         BigFloat = 5,
 
-        /// <summary>
-        ///   Tag value for byte strings, meant for later encoding to a base64url string representation.
-        /// </summary>
+        /// <summary>Tag value for byte strings, meant for later encoding to a base64url string representation.</summary>
         Base64UrlLaterEncoding = 21,
 
-        /// <summary>
-        ///   Tag value for byte strings, meant for later encoding to a base64 string representation.
-        /// </summary>
+        /// <summary>Tag value for byte strings, meant for later encoding to a base64 string representation.</summary>
         Base64StringLaterEncoding = 22,
 
-        /// <summary>
-        ///   Tag value for byte strings, meant for later encoding to a base16 string representation.
-        /// </summary>
+        /// <summary>Tag value for byte strings, meant for later encoding to a base16 string representation.</summary>
         Base16StringLaterEncoding = 23,
 
-        /// <summary>
-        ///   Tag value for byte strings containing embedded CBOR data item encodings.
-        /// </summary>
+        /// <summary>Tag value for byte strings containing embedded CBOR data item encodings.</summary>
         EncodedCborDataItem = 24,
 
-        /// <summary>
-        ///   Tag value for Uri strings, as defined in RFC3986.
-        /// </summary>
+        /// <summary>Tag value for Uri strings, as defined in RFC3986.</summary>
         Uri = 32,
 
-        /// <summary>
-        ///   Tag value for base64url-encoded text strings, as defined in RFC4648.
-        /// </summary>
+        /// <summary>Tag value for base64url-encoded text strings, as defined in RFC4648.</summary>
         Base64Url = 33,
 
-        /// <summary>
-        ///   Tag value for base64-encoded text strings, as defined in RFC4648.
-        /// </summary>
+        /// <summary>Tag value for base64-encoded text strings, as defined in RFC4648.</summary>
         Base64 = 34,
 
-        /// <summary>
-        ///   Tag value for regular expressions in Perl Compatible Regular Expressions / Javascript syntax.
-        /// </summary>
+        /// <summary>Tag value for regular expressions in Perl Compatible Regular Expressions / Javascript syntax.</summary>
         Regex = 35,
 
-        /// <summary>
-        ///   Tag value for MIME messages (including all headers), as defined in RFC2045.
-        /// </summary>
+        /// <summary>Tag value for MIME messages (including all headers), as defined in RFC2045.</summary>
         MimeMessage = 36,
 
-        /// <summary>
-        ///   Tag value for the Self-Describe CBOR header (0xd9d9f7).
-        /// </summary>
+        /// <summary>Tag value for the Self-Describe CBOR header (0xd9d9f7).</summary>
         SelfDescribeCbor = 55799,
     }
 
-    /// <summary>
-    ///   Represents a CBOR simple value (major type 7).
-    /// </summary>
+    /// <summary>Represents a CBOR simple value (major type 7).</summary>
     public enum CborSimpleValue : byte
     {
-        /// <summary>
-        ///   Represents the value 'false'.
-        /// </summary>
+        /// <summary>Represents the value 'false'.</summary>
         False = 20,
 
-        /// <summary>
-        ///   Represents the value 'true'.
-        /// </summary>
+        /// <summary>Represents the value 'true'.</summary>
         True = 21,
 
-        /// <summary>
-        ///   Represents the value 'null'.
-        /// </summary>
+        /// <summary>Represents the value 'null'.</summary>
         Null = 22,
 
-        /// <summary>
-        ///   Represents an undefined value, to be used by an encoder
-        ///   as a substitute for a data item with an encoding problem.
-        /// </summary>
+        /// <summary>Represents an undefined value, to be used by an encoder as a substitute for a data item with an encoding problem.</summary>
         Undefined = 23,
     }
 }
diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Array.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Array.cs
@@ -5,20 +5,14 @@ namespace System.Formats.Cbor
 {
     public partial class CborReader
     {
-        /// <summary>
-        ///   Reads the next data item as the start of an array (major type 4).
-        /// </summary>
-        /// <returns>
-        ///   The length of the definite-length array, or <see langword="null" /> if the array is indefinite-length.
-        /// </returns>
-        /// <exception cref="InvalidOperationException">
-        ///   the next data item does not have the correct major type.
-        /// </exception>
-        /// <exception cref="CborContentException">
-        ///   the next value has an invalid CBOR encoding. -or-
-        ///   there was an unexpected end of CBOR encoding data. -or-
-        ///   the next value uses a CBOR encoding that is not valid under the current conformance mode.
-        /// </exception>
+        /// <summary>Reads the next data item as the start of an array (major type 4).</summary>
+        /// <returns>The length of the definite-length array, or <see langword="null" /> if the array is indefinite-length.</returns>
+        /// <exception cref="InvalidOperationException">The next data item does not have the correct major type.</exception>
+        /// <exception cref="CborContentException">The next value has an invalid CBOR encoding.
+        /// -or-
+        /// There was an unexpected end of CBOR encoding data.
+        /// -or-
+        /// The next value uses a CBOR encoding that is not valid under the current conformance mode.</exception>
         public int? ReadStartArray()
         {
             CborInitialByte header = PeekInitialByte(expectedType: CborMajorType.Array);
@@ -45,17 +39,13 @@ public partial class CborReader
             }
         }
 
-        /// <summary>
-        ///   Reads the end of an array (major type 4).
-        /// </summary>
-        /// <exception cref="InvalidOperationException">
-        ///   the current context is not an array. -or-
-        ///   the reader is not at the end of the array.
-        /// </exception>
-        /// <exception cref="CborContentException">
-        ///   the next value has an invalid CBOR encoding. -or-
-        ///   there was an unexpected end of CBOR encoding data
-        /// </exception>
+        /// <summary>Reads the end of an array (major type 4).</summary>
+        /// <exception cref="InvalidOperationException">The current context is not an array.
+        /// -or-
+        /// The reader is not at the end of the array.</exception>
+        /// <exception cref="CborContentException">The next value has an invalid CBOR encoding.
+        /// -or-
+        /// There was an unexpected end of CBOR encoding data.</exception>
         public void ReadEndArray()
         {
             if (_definiteLength is null)