[release/9.0] Make System.Formats.Asn1 triple slash documentation the…

… source of truth (#108995) * Port System.Formats.Asn1 docs to triple slash * Change System.Formats.Asn1 docs to be the source of truth * Add missing documentation * Documentation feedback. Co-authored-by: Genevieve Warren <[email protected]> Co-authored-by: Jeremy Barton <[email protected]> * Documentation feedback. Co-authored-by: Jeremy Barton <[email protected]> * Missed one. Co-authored-by: Genevieve Warren <[email protected]> --------- Co-authored-by: Kevin Jones <[email protected]> Co-authored-by: Genevieve Warren <[email protected]> Co-authored-by: Jeremy Barton <[email protected]>
dotnet · Oct 18, 2024 · b678c8a · b678c8a
1 parent 093129f
commit b678c8a
Show file tree

Hide file tree

Showing 26 changed files with 360 additions and 312 deletions.
diff --git a/src/libraries/System.Formats.Asn1/src/System.Formats.Asn1.csproj b/src/libraries/System.Formats.Asn1/src/System.Formats.Asn1.csproj
@@ -4,7 +4,6 @@
     <TargetFrameworks>$(NetCoreAppCurrent);$(NetCoreAppPrevious);$(NetCoreAppMinimum);netstandard2.0;$(NetFrameworkMinimum)</TargetFrameworks>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <DefineConstants>$(DefineConstants);CP_NO_ZEROMEMORY</DefineConstants>
-    <UseCompilerGeneratedDocXmlFile>false</UseCompilerGeneratedDocXmlFile>
     <IsPackable>true</IsPackable>
     <PackageDescription>Provides classes that can read and write the ASN.1 BER, CER, and DER data formats.</PackageDescription>
   </PropertyGroup>

diff --git a/src/libraries/System.Formats.Asn1/src/System/Formats/Asn1/Asn1Tag.Accelerators.cs b/src/libraries/System.Formats.Asn1/src/System/Formats/Asn1/Asn1Tag.Accelerators.cs
@@ -43,7 +43,7 @@ public partial struct Asn1Tag
             new Asn1Tag(ConstructedMask, (int)UniversalTagNumber.OctetString);
 
         /// <summary>
-        ///   Represents the universal class tag for a Null value.
+        ///   Represents the universal class tag for a <c>Null</c> value.
         /// </summary>
         public static readonly Asn1Tag Null = new Asn1Tag(0, (int)UniversalTagNumber.Null);
 

diff --git a/src/libraries/System.Formats.Asn1/src/System/Formats/Asn1/AsnContentException.cs b/src/libraries/System.Formats.Asn1/src/System/Formats/Asn1/AsnContentException.cs
@@ -6,24 +6,55 @@
 
 namespace System.Formats.Asn1
 {
+    /// <summary>
+    ///   The exception that is thrown when an encoded ASN.1 value cannot be successfully decoded.
+    /// </summary>
     [Serializable]
     public class AsnContentException : Exception
     {
+        /// <summary>
+        ///   Initializes a new instance of the <see cref="AsnContentException" /> class, using the default message.
+        /// </summary>
         public AsnContentException()
             : base(SR.ContentException_DefaultMessage)
         {
         }
 
+        /// <summary>
+        ///   Initializes a new instance of the <see cref="AsnContentException" /> class, using the provided message.
+        /// </summary>
+        /// <param name="message">
+        ///   The error message that explains the reason for the exception.
+        /// </param>
         public AsnContentException(string? message)
             : base(message ?? SR.ContentException_DefaultMessage)
         {
         }
 
+        /// <summary>
+        ///   Initializes a new instance of the <see cref="AsnContentException" /> 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>
+        /// <param name="inner">
+        ///   The exception that is the cause of the current exception.
+        /// </param>
         public AsnContentException(string? message, Exception? inner)
             : base(message ?? SR.ContentException_DefaultMessage, inner)
         {
         }
 
+        /// <summary>
+        ///   Initializes a new instance of the <see cref="AsnContentException" /> 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>
 #if NET8_0_OR_GREATER
         [Obsolete(Obsoletions.LegacyFormatterImplMessage, DiagnosticId = Obsoletions.LegacyFormatterImplDiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
         [EditorBrowsable(EditorBrowsableState.Never)]

diff --git a/src/libraries/System.Formats.Asn1/src/System/Formats/Asn1/AsnDecoder.BitString.cs b/src/libraries/System.Formats.Asn1/src/System/Formats/Asn1/AsnDecoder.BitString.cs
@@ -41,15 +41,15 @@ public static partial class AsnDecoder
         ///   <paramref name="ruleSet"/> is not defined.
         /// </exception>
         /// <exception cref="AsnContentException">
-        ///   the next value does not have the correct tag.
+        ///   The next value does not have the correct tag.
         ///
         ///   -or-
         ///
-        ///   the length encoding is not valid under the current encoding rules.
+        ///   The length encoding is not valid under the current encoding rules.
         ///
         ///   -or-
         ///
-        ///   the contents are not valid under the current encoding rules.
+        ///   The contents are not valid under the current encoding rules.
         /// </exception>
         /// <exception cref="ArgumentException">
         ///   <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagClass"/> is
@@ -122,24 +122,19 @@ public static bool TryReadPrimitiveBitString(
         ///   value of the Bit String;
         ///   otherwise, <see langword="false"/>.
         /// </returns>
-        /// <remarks>
-        ///   The least significant bits in the last byte which are reported as "unused" by the
-        ///   <paramref name="unusedBitCount"/> value will be copied into <paramref name="destination"/>
-        ///   as unset bits, irrespective of their value in the encoded representation.
-        /// </remarks>
         /// <exception cref="ArgumentOutOfRangeException">
         ///   <paramref name="ruleSet"/> is not defined.
         /// </exception>
         /// <exception cref="AsnContentException">
-        ///   the next value does not have the correct tag.
+        ///   The next value does not have the correct tag.
         ///
         ///   -or-
         ///
-        ///   the length encoding is not valid under the current encoding rules.
+        ///   The length encoding is not valid under the current encoding rules.
         ///
         ///   -or-
         ///
-        ///   the contents are not valid under the current encoding rules.
+        ///   The contents are not valid under the current encoding rules.
         /// </exception>
         /// <exception cref="ArgumentException">
         ///   <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagClass"/> is
@@ -151,6 +146,11 @@ public static bool TryReadPrimitiveBitString(
         ///
         ///   <paramref name="destination"/> overlaps <paramref name="source"/>.
         /// </exception>
+        /// <remarks>
+        ///   The least significant bits in the last byte that are reported as "unused" by the
+        ///   <paramref name="unusedBitCount"/> value will be copied into <paramref name="destination"/>
+        ///   as unset bits, irrespective of their value in the encoded representation.
+        /// </remarks>
         /// <seealso cref="TryReadPrimitiveBitString"/>
         /// <seealso cref="ReadBitString"/>
         public static bool TryReadBitString(
@@ -244,31 +244,31 @@ public static bool TryReadBitString(
         /// <returns>
         ///   An array containing the contents of the Bit String value.
         /// </returns>
-        /// <remarks>
-        ///   The least significant bits in the last byte which are reported as "unused" by the
-        ///   <paramref name="unusedBitCount"/> value will be copied into the return value
-        ///   as unset bits, irrespective of their value in the encoded representation.
-        /// </remarks>
         /// <exception cref="ArgumentOutOfRangeException">
         ///   <paramref name="ruleSet"/> is not defined.
         /// </exception>
         /// <exception cref="AsnContentException">
-        ///   the next value does not have the correct tag.
+        ///   The next value does not have the correct tag.
         ///
         ///   -or-
         ///
-        ///   the length encoding is not valid under the current encoding rules.
+        ///   The length encoding is not valid under the current encoding rules.
         ///
         ///   -or-
         ///
-        ///   the contents are not valid under the current encoding rules.
+        ///   The contents are not valid under the current encoding rules.
         /// </exception>
         /// <exception cref="ArgumentException">
         ///   <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagClass"/> is
         ///   <see cref="TagClass.Universal"/>, but
         ///   <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagValue"/> is not correct for
         ///   the method.
         /// </exception>
+        /// <remarks>
+        ///   The least significant bits in the last byte that are reported as "unused" by the
+        ///   <paramref name="unusedBitCount"/> value will be copied into the return value
+        ///   as unset bits, irrespective of their value in the encoded representation.
+        /// </remarks>
         /// <seealso cref="TryReadPrimitiveBitString"/>
         /// <seealso cref="TryReadBitString"/>
         public static byte[] ReadBitString(
@@ -696,15 +696,15 @@ public partial class AsnReader
         ///   <see langword="false"/> and does not advance the reader if it had a constructed encoding.
         /// </returns>
         /// <exception cref="AsnContentException">
-        ///   the next value does not have the correct tag.
+        ///   The next value does not have the correct tag.
         ///
         ///   -or-
         ///
-        ///   the length encoding is not valid under the current encoding rules.
+        ///   The length encoding is not valid under the current encoding rules.
         ///
         ///   -or-
         ///
-        ///   the contents are not valid under the current encoding rules.
+        ///   The contents are not valid under the current encoding rules.
         /// </exception>
         /// <exception cref="ArgumentException">
         ///   <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagClass"/> is
@@ -760,15 +760,15 @@ public bool TryReadPrimitiveBitString(
         ///   <see langword="false"/> and the reader does not advance.
         /// </returns>
         /// <exception cref="AsnContentException">
-        ///   the next value does not have the correct tag.
+        ///   The next value does not have the correct tag.
         ///
         ///   -or-
         ///
-        ///   the length encoding is not valid under the current encoding rules.
+        ///   The length encoding is not valid under the current encoding rules.
         ///
         ///   -or-
         ///
-        ///   the contents are not valid under the current encoding rules.
+        ///   The contents are not valid under the current encoding rules.
         /// </exception>
         /// <exception cref="ArgumentException">
         ///   <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagClass"/> is
@@ -816,15 +816,15 @@ public bool TryReadBitString(
         ///   A copy of the value in a newly allocated, precisely sized, array.
         /// </returns>
         /// <exception cref="AsnContentException">
-        ///   the next value does not have the correct tag.
+        ///   The next value does not have the correct tag.
         ///
         ///   -or-
         ///
-        ///   the length encoding is not valid under the current encoding rules.
+        ///   The length encoding is not valid under the current encoding rules.
         ///
         ///   -or-
         ///
-        ///   the contents are not valid under the current encoding rules.
+        ///   The contents are not valid under the current encoding rules.
         /// </exception>
         /// <exception cref="ArgumentException">
         ///   <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagClass"/> is

diff --git a/src/libraries/System.Formats.Asn1/src/System/Formats/Asn1/AsnDecoder.Boolean.cs b/src/libraries/System.Formats.Asn1/src/System/Formats/Asn1/AsnDecoder.Boolean.cs
@@ -25,15 +25,15 @@ public static partial class AsnDecoder
         ///   <paramref name="ruleSet"/> is not defined.
         /// </exception>
         /// <exception cref="AsnContentException">
-        ///   the next value does not have the correct tag.
+        ///   The next value does not have the correct tag.
         ///
         ///   -or-
         ///
-        ///   the length encoding is not valid under the current encoding rules.
+        ///   The length encoding is not valid under the current encoding rules.
         ///
         ///   -or-
         ///
-        ///   the contents are not valid under the current encoding rules.
+        ///   The contents are not valid under the current encoding rules.
         /// </exception>
         /// <exception cref="ArgumentException">
         ///   <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagClass"/> is
@@ -93,15 +93,15 @@ public partial class AsnReader
         ///   The decoded value.
         /// </returns>
         /// <exception cref="AsnContentException">
-        ///   the next value does not have the correct tag.
+        ///   The next value does not have the correct tag.
         ///
         ///   -or-
         ///
-        ///   the length encoding is not valid under the current encoding rules.
+        ///   The length encoding is not valid under the current encoding rules.
         ///
         ///   -or-
         ///
-        ///   the contents are not valid under the current encoding rules.
+        ///   The contents are not valid under the current encoding rules.
         /// </exception>
         /// <exception cref="ArgumentException">
         ///   <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagClass"/> is