Skip to content

Make System.Formats.Asn1 triple slash documentation the source of truth #108982

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Oct 17, 2024
Merged

Make System.Formats.Asn1 triple slash documentation the source of truth #108982

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
336ebf9
Port System.Formats.Asn1 docs to triple slash
vcsjones Oct 17, 2024
2968b56
Change System.Formats.Asn1 docs to be the source of truth
vcsjones Oct 17, 2024
3421ba2
Add missing documentation
vcsjones Oct 17, 2024
cf4a045
Documentation feedback.
vcsjones Oct 17, 2024
efa2fa2
Documentation feedback.
vcsjones Oct 17, 2024
747de52
Missed one.
vcsjones Oct 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion src/libraries/System.Formats.Asn1/src/System.Formats.Asn1.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
2 changes: 1 addition & 1 deletion src/libraries/System.Formats.Asn1/src/System/Formats/Asn1/Asn1Tag.Accelerators.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <see langword="null" /> value.
/// </summary>
public static readonly Asn1Tag Null = new Asn1Tag(0, (int)UniversalTagNumber.Null);

Expand Down
31 changes: 31 additions & 0 deletions src/libraries/System.Formats.Asn1/src/System/Formats/Asn1/AsnContentException.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)]
Expand Down
56 changes: 28 additions & 28 deletions src/libraries/System.Formats.Asn1/src/System/Formats/Asn1/AsnDecoder.BitString.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These might need <para> tags so they remain on separate lines in the docs, right @carlossanlop?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see now that that would mean a lot of changes throughout this PR. I'm also fine with not adding them.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The porttotripleslash tool did not put <para> there, so I assumed it was not required.

///
/// -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
Expand Down Expand Up @@ -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
Expand All @@ -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 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>
/// <seealso cref="TryReadPrimitiveBitString"/>
/// <seealso cref="ReadBitString"/>
public static bool TryReadBitString(
Expand Down Expand Up @@ -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 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>
/// <seealso cref="TryReadPrimitiveBitString"/>
/// <seealso cref="TryReadBitString"/>
public static byte[] ReadBitString(
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
12 changes: 6 additions & 6 deletions src/libraries/System.Formats.Asn1/src/System/Formats/Asn1/AsnDecoder.Boolean.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading
Loading