Skip to content

Commit b678c8a

Browse files
github-actions[bot]vcsjonesgewarrenbartonjs
authored
[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]>
1 parent 093129f commit b678c8a

26 files changed

+360
-312
lines changed

‎src/libraries/System.Formats.Asn1/src/System.Formats.Asn1.csproj‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@
44
<TargetFrameworks>$(NetCoreAppCurrent);$(NetCoreAppPrevious);$(NetCoreAppMinimum);netstandard2.0;$(NetFrameworkMinimum)</TargetFrameworks>
55
<AllowUnsafeBlocks>true</AllowUnsafeBlocks>
66
<DefineConstants>$(DefineConstants);CP_NO_ZEROMEMORY</DefineConstants>
7-
<UseCompilerGeneratedDocXmlFile>false</UseCompilerGeneratedDocXmlFile>
87
<IsPackable>true</IsPackable>
98
<PackageDescription>Provides classes that can read and write the ASN.1 BER, CER, and DER data formats.</PackageDescription>
109
</PropertyGroup>

‎src/libraries/System.Formats.Asn1/src/System/Formats/Asn1/Asn1Tag.Accelerators.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ public partial struct Asn1Tag
4343
new Asn1Tag(ConstructedMask, (int)UniversalTagNumber.OctetString);
4444

4545
/// <summary>
46-
/// Represents the universal class tag for a Null value.
46+
/// Represents the universal class tag for a <c>Null</c> value.
4747
/// </summary>
4848
public static readonly Asn1Tag Null = new Asn1Tag(0, (int)UniversalTagNumber.Null);
4949

‎src/libraries/System.Formats.Asn1/src/System/Formats/Asn1/AsnContentException.cs‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,24 +6,55 @@
66

77
namespace System.Formats.Asn1
88
{
9+
/// <summary>
10+
/// The exception that is thrown when an encoded ASN.1 value cannot be successfully decoded.
11+
/// </summary>
912
[Serializable]
1013
public class AsnContentException : Exception
1114
{
15+
/// <summary>
16+
/// Initializes a new instance of the <see cref="AsnContentException" /> class, using the default message.
17+
/// </summary>
1218
public AsnContentException()
1319
: base(SR.ContentException_DefaultMessage)
1420
{
1521
}
1622

23+
/// <summary>
24+
/// Initializes a new instance of the <see cref="AsnContentException" /> class, using the provided message.
25+
/// </summary>
26+
/// <param name="message">
27+
/// The error message that explains the reason for the exception.
28+
/// </param>
1729
public AsnContentException(string? message)
1830
: base(message ?? SR.ContentException_DefaultMessage)
1931
{
2032
}
2133

34+
/// <summary>
35+
/// Initializes a new instance of the <see cref="AsnContentException" /> class, using the provided message and
36+
/// exception that is the cause of this exception.
37+
/// </summary>
38+
/// <param name="message">
39+
/// The error message that explains the reason for the exception.
40+
/// </param>
41+
/// <param name="inner">
42+
/// The exception that is the cause of the current exception.
43+
/// </param>
2244
public AsnContentException(string? message, Exception? inner)
2345
: base(message ?? SR.ContentException_DefaultMessage, inner)
2446
{
2547
}
2648

49+
/// <summary>
50+
/// Initializes a new instance of the <see cref="AsnContentException" /> class with serialized data.
51+
/// </summary>
52+
/// <param name="info">
53+
/// The object that holds the serialized object data.
54+
/// </param>
55+
/// <param name="context">
56+
/// The contextual information about the source or destination.
57+
/// </param>
2758
#if NET8_0_OR_GREATER
2859
[Obsolete(Obsoletions.LegacyFormatterImplMessage, DiagnosticId = Obsoletions.LegacyFormatterImplDiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
2960
[EditorBrowsable(EditorBrowsableState.Never)]

‎src/libraries/System.Formats.Asn1/src/System/Formats/Asn1/AsnDecoder.BitString.cs‎

Lines changed: 28 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -41,15 +41,15 @@ public static partial class AsnDecoder
4141
/// <paramref name="ruleSet"/> is not defined.
4242
/// </exception>
4343
/// <exception cref="AsnContentException">
44-
/// the next value does not have the correct tag.
44+
/// The next value does not have the correct tag.
4545
///
4646
/// -or-
4747
///
48-
/// the length encoding is not valid under the current encoding rules.
48+
/// The length encoding is not valid under the current encoding rules.
4949
///
5050
/// -or-
5151
///
52-
/// the contents are not valid under the current encoding rules.
52+
/// The contents are not valid under the current encoding rules.
5353
/// </exception>
5454
/// <exception cref="ArgumentException">
5555
/// <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagClass"/> is
@@ -122,24 +122,19 @@ public static bool TryReadPrimitiveBitString(
122122
/// value of the Bit String;
123123
/// otherwise, <see langword="false"/>.
124124
/// </returns>
125-
/// <remarks>
126-
/// The least significant bits in the last byte which are reported as "unused" by the
127-
/// <paramref name="unusedBitCount"/> value will be copied into <paramref name="destination"/>
128-
/// as unset bits, irrespective of their value in the encoded representation.
129-
/// </remarks>
130125
/// <exception cref="ArgumentOutOfRangeException">
131126
/// <paramref name="ruleSet"/> is not defined.
132127
/// </exception>
133128
/// <exception cref="AsnContentException">
134-
/// the next value does not have the correct tag.
129+
/// The next value does not have the correct tag.
135130
///
136131
/// -or-
137132
///
138-
/// the length encoding is not valid under the current encoding rules.
133+
/// The length encoding is not valid under the current encoding rules.
139134
///
140135
/// -or-
141136
///
142-
/// the contents are not valid under the current encoding rules.
137+
/// The contents are not valid under the current encoding rules.
143138
/// </exception>
144139
/// <exception cref="ArgumentException">
145140
/// <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagClass"/> is
@@ -151,6 +146,11 @@ public static bool TryReadPrimitiveBitString(
151146
///
152147
/// <paramref name="destination"/> overlaps <paramref name="source"/>.
153148
/// </exception>
149+
/// <remarks>
150+
/// The least significant bits in the last byte that are reported as "unused" by the
151+
/// <paramref name="unusedBitCount"/> value will be copied into <paramref name="destination"/>
152+
/// as unset bits, irrespective of their value in the encoded representation.
153+
/// </remarks>
154154
/// <seealso cref="TryReadPrimitiveBitString"/>
155155
/// <seealso cref="ReadBitString"/>
156156
public static bool TryReadBitString(
@@ -244,31 +244,31 @@ public static bool TryReadBitString(
244244
/// <returns>
245245
/// An array containing the contents of the Bit String value.
246246
/// </returns>
247-
/// <remarks>
248-
/// The least significant bits in the last byte which are reported as "unused" by the
249-
/// <paramref name="unusedBitCount"/> value will be copied into the return value
250-
/// as unset bits, irrespective of their value in the encoded representation.
251-
/// </remarks>
252247
/// <exception cref="ArgumentOutOfRangeException">
253248
/// <paramref name="ruleSet"/> is not defined.
254249
/// </exception>
255250
/// <exception cref="AsnContentException">
256-
/// the next value does not have the correct tag.
251+
/// The next value does not have the correct tag.
257252
///
258253
/// -or-
259254
///
260-
/// the length encoding is not valid under the current encoding rules.
255+
/// The length encoding is not valid under the current encoding rules.
261256
///
262257
/// -or-
263258
///
264-
/// the contents are not valid under the current encoding rules.
259+
/// The contents are not valid under the current encoding rules.
265260
/// </exception>
266261
/// <exception cref="ArgumentException">
267262
/// <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagClass"/> is
268263
/// <see cref="TagClass.Universal"/>, but
269264
/// <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagValue"/> is not correct for
270265
/// the method.
271266
/// </exception>
267+
/// <remarks>
268+
/// The least significant bits in the last byte that are reported as "unused" by the
269+
/// <paramref name="unusedBitCount"/> value will be copied into the return value
270+
/// as unset bits, irrespective of their value in the encoded representation.
271+
/// </remarks>
272272
/// <seealso cref="TryReadPrimitiveBitString"/>
273273
/// <seealso cref="TryReadBitString"/>
274274
public static byte[] ReadBitString(
@@ -696,15 +696,15 @@ public partial class AsnReader
696696
/// <see langword="false"/> and does not advance the reader if it had a constructed encoding.
697697
/// </returns>
698698
/// <exception cref="AsnContentException">
699-
/// the next value does not have the correct tag.
699+
/// The next value does not have the correct tag.
700700
///
701701
/// -or-
702702
///
703-
/// the length encoding is not valid under the current encoding rules.
703+
/// The length encoding is not valid under the current encoding rules.
704704
///
705705
/// -or-
706706
///
707-
/// the contents are not valid under the current encoding rules.
707+
/// The contents are not valid under the current encoding rules.
708708
/// </exception>
709709
/// <exception cref="ArgumentException">
710710
/// <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagClass"/> is
@@ -760,15 +760,15 @@ public bool TryReadPrimitiveBitString(
760760
/// <see langword="false"/> and the reader does not advance.
761761
/// </returns>
762762
/// <exception cref="AsnContentException">
763-
/// the next value does not have the correct tag.
763+
/// The next value does not have the correct tag.
764764
///
765765
/// -or-
766766
///
767-
/// the length encoding is not valid under the current encoding rules.
767+
/// The length encoding is not valid under the current encoding rules.
768768
///
769769
/// -or-
770770
///
771-
/// the contents are not valid under the current encoding rules.
771+
/// The contents are not valid under the current encoding rules.
772772
/// </exception>
773773
/// <exception cref="ArgumentException">
774774
/// <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagClass"/> is
@@ -816,15 +816,15 @@ public bool TryReadBitString(
816816
/// A copy of the value in a newly allocated, precisely sized, array.
817817
/// </returns>
818818
/// <exception cref="AsnContentException">
819-
/// the next value does not have the correct tag.
819+
/// The next value does not have the correct tag.
820820
///
821821
/// -or-
822822
///
823-
/// the length encoding is not valid under the current encoding rules.
823+
/// The length encoding is not valid under the current encoding rules.
824824
///
825825
/// -or-
826826
///
827-
/// the contents are not valid under the current encoding rules.
827+
/// The contents are not valid under the current encoding rules.
828828
/// </exception>
829829
/// <exception cref="ArgumentException">
830830
/// <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagClass"/> is

‎src/libraries/System.Formats.Asn1/src/System/Formats/Asn1/AsnDecoder.Boolean.cs‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -25,15 +25,15 @@ public static partial class AsnDecoder
2525
/// <paramref name="ruleSet"/> is not defined.
2626
/// </exception>
2727
/// <exception cref="AsnContentException">
28-
/// the next value does not have the correct tag.
28+
/// The next value does not have the correct tag.
2929
///
3030
/// -or-
3131
///
32-
/// the length encoding is not valid under the current encoding rules.
32+
/// The length encoding is not valid under the current encoding rules.
3333
///
3434
/// -or-
3535
///
36-
/// the contents are not valid under the current encoding rules.
36+
/// The contents are not valid under the current encoding rules.
3737
/// </exception>
3838
/// <exception cref="ArgumentException">
3939
/// <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagClass"/> is
@@ -93,15 +93,15 @@ public partial class AsnReader
9393
/// The decoded value.
9494
/// </returns>
9595
/// <exception cref="AsnContentException">
96-
/// the next value does not have the correct tag.
96+
/// The next value does not have the correct tag.
9797
///
9898
/// -or-
9999
///
100-
/// the length encoding is not valid under the current encoding rules.
100+
/// The length encoding is not valid under the current encoding rules.
101101
///
102102
/// -or-
103103
///
104-
/// the contents are not valid under the current encoding rules.
104+
/// The contents are not valid under the current encoding rules.
105105
/// </exception>
106106
/// <exception cref="ArgumentException">
107107
/// <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagClass"/> is

0 commit comments

Comments
 (0)