dotnet: add XML doc comments to pcf-sig public surface

The .NET CI failed CS1591 (\"Missing XML comment for publicly visible
type or member\") on every public field, property and factory method
that I had left undocumented. Pcf.Sig.csproj enables
<GenerateDocumentationFile>true</GenerateDocumentationFile> the same
way PCF does, and PCF achieves full coverage by documenting everything;
match that bar here rather than suppressing the warning.

Added missing summaries on:
  - KeyRecord: VersionMajor/Minor, KeyFormat, Fingerprint, KeyData,
    Metadata
  - KeyMetadata: Tag, Value, constructor
  - SignedEntry: Uid, PartitionType, Label, UsedBytes, DataHashAlgo,
    DataHash
  - Manifest: VersionMajor/Minor, SigAlgo, ManifestHashAlgo, Flags,
    SignerKeyFingerprint, SignedAtUnixSeconds, SignedEntries
  - SignaturePartition: Manifest, ManifestBytes, Signature, Trailer
  - SigningMaterial: SigAlgo, KeyFormat, PublicKeyBytes properties
  - PcfSigException: Kind property, constructor, and all 23 static
    factory methods; PcfSigErrorKind: all 23 enum members
  - SigAlgoExtensions/KeyFormatExtensions: FromId/Id/IsImplemented
  - Verify.cs: EntryVerdict + ManifestVerdict + UnverifiableReason
    + DataRecheck enum members; EntryReport.Uid/Verdict/ctor;
    SignatureReport.SigPartitionUid/SignerKeyFingerprint/SignedAtUnixSeconds/Verdict/UnverifiableReason/UnverifiableId/Entries

LittleEndian remains internal so its public methods don't count as
publicly visible and need no docs.

https://claude.ai/code/session_01ST4PcjqvobURus32WuyEi5

Author: claude

implementations/dotnet/pcf-sig/src/Pcf.Sig/KeyRecord.cs

@@ -8,9 +8,13 @@ namespace Pcf.Sig;
 /// <summary>One metadata TLV entry (spec Section 6.4).</summary>
 public sealed class KeyMetadata
 {
+    /// <summary>16-bit tag from the metadata registry (spec Appendix B).</summary>
     public ushort Tag { get; }
+
+    /// <summary>Value bytes; interpretation depends on <see cref="Tag"/>.</summary>
     public byte[] Value { get; }
 
+    /// <summary>Construct a metadata entry from a tag and a value.</summary>
     public KeyMetadata(ushort tag, byte[] value)
     {
         Tag = tag;
@@ -21,11 +25,22 @@ public KeyMetadata(ushort tag, byte[] value)
 /// <summary>A parsed Key Record (spec Section 6).</summary>
 public sealed class KeyRecord
 {
+    /// <summary><c>record_version_major</c>. v1.0 implementations require 1.</summary>
     public ushort VersionMajor { get; set; }
+
+    /// <summary><c>record_version_minor</c>.</summary>
     public ushort VersionMinor { get; set; }
+
+    /// <summary><c>key_format_id</c> (spec Section 6.2).</summary>
     public KeyFormat KeyFormat { get; set; }
+
+    /// <summary>32-byte SHA-256 fingerprint of <see cref="KeyData"/> (spec Section 6.3).</summary>
     public byte[] Fingerprint { get; set; } = new byte[Constants.FingerprintSize];
+
+    /// <summary>Raw key material in the encoding named by <see cref="KeyFormat"/>.</summary>
     public byte[] KeyData { get; set; } = new byte[0];
+
+    /// <summary>Optional metadata entries (spec Section 6.4).</summary>
     public List<KeyMetadata> Metadata { get; set; } = new();
 
     /// <summary>Build a Key Record from raw key bytes; fills version + fingerprint.</summary>

implementations/dotnet/pcf-sig/src/Pcf.Sig/Manifest.cs

@@ -7,11 +7,22 @@ namespace Pcf.Sig;
 /// <summary>One Signed Entry inside a Manifest (spec Section 7.2).</summary>
 public sealed class SignedEntry
 {
+    /// <summary>PCF uid of the covered partition (verbatim).</summary>
     public byte[] Uid { get; set; } = new byte[Pcf.Constants.UidSize];
+
+    /// <summary>PCF type of the covered partition (verbatim).</summary>
     public uint PartitionType { get; set; }
+
+    /// <summary>PCF label of the covered partition (verbatim 32-byte field).</summary>
     public byte[] Label { get; set; } = new byte[Pcf.Constants.LabelSize];
+
+    /// <summary>PCF <c>used_bytes</c> of the covered partition.</summary>
     public ulong UsedBytes { get; set; }
+
+    /// <summary>PCF <c>data_hash_algo_id</c>. MUST be cryptographic in v1.0 (16/17/18).</summary>
     public HashAlgo DataHashAlgo { get; set; }
+
+    /// <summary>PCF <c>data_hash</c> field bytes (verbatim 64-byte field).</summary>
     public byte[] DataHash { get; set; } = new byte[Pcf.Constants.HashFieldSize];
 
     /// <summary>Serialise to the on-disk 218-byte layout.</summary>
@@ -93,13 +104,31 @@ private static bool IsAllZero(byte[] b)
 /// <summary>A parsed Manifest (spec Section 7.1).</summary>
 public sealed class Manifest
 {
+    /// <summary><c>manifest_version_major</c>.</summary>
     public ushort VersionMajor { get; set; }
+
+    /// <summary><c>manifest_version_minor</c>.</summary>
     public ushort VersionMinor { get; set; }
+
+    /// <summary><c>sig_algo_id</c>.</summary>
     public SigAlgo SigAlgo { get; set; }
+
+    /// <summary>
+    /// <c>manifest_hash_algo_id</c>. MUST be cryptographic (16/17/18) and MUST
+    /// satisfy the binding required by <see cref="SigAlgo"/>.
+    /// </summary>
     public HashAlgo ManifestHashAlgo { get; set; }
+
+    /// <summary>Reserved <c>flags</c> field; v1.0 MUST be 0.</summary>
     public ushort Flags { get; set; }
+
+    /// <summary>Signer key fingerprint (SHA-256 of the matching PCFSIG_KEY's <c>key_data</c>).</summary>
     public byte[] SignerKeyFingerprint { get; set; } = new byte[Constants.FingerprintSize];
+
+    /// <summary><c>signed_at_unix_seconds</c> (i64).</summary>
     public long SignedAtUnixSeconds { get; set; }
+
+    /// <summary><c>signed_entries</c>, packed in writer-chosen order.</summary>
     public List<SignedEntry> SignedEntries { get; set; } = new();
 
     /// <summary>Construct a Manifest from its component parts.</summary>

implementations/dotnet/pcf-sig/src/Pcf.Sig/PcfSigException.cs

@@ -5,118 +5,166 @@ namespace Pcf.Sig;
 /// <summary>Discriminant identifying which kind of <see cref="PcfSigException"/> occurred.</summary>
 public enum PcfSigErrorKind
 {
+    /// <summary>A Key Record did not begin with <c>"PCFKEY\0\0"</c>.</summary>
     BadKeyMagic,
+    /// <summary>A Manifest did not begin with <c>"PCFSIG\0\0"</c>.</summary>
     BadManifestMagic,
+    /// <summary>A record's profile major version is not implemented by this library.</summary>
     UnsupportedMajor,
+    /// <summary>A Key Record's <c>key_format_id</c> is unknown or reserved (0).</summary>
     UnknownKeyFormat,
+    /// <summary>A Key Record's <c>key_data_length</c> is zero.</summary>
     EmptyKeyData,
+    /// <summary>A Key Record's reserved bytes are non-zero in v1.0.</summary>
     NonZeroKeyReserved,
+    /// <summary><c>fingerprint</c> does not equal <c>SHA-256(key_data)</c>.</summary>
     FingerprintMismatch,
+    /// <summary>A Manifest's <c>sig_algo_id</c> is reserved (0) or unknown.</summary>
     UnknownSigAlgo,
+    /// <summary>A Manifest's <c>manifest_hash_algo_id</c> is not cryptographic.</summary>
     NonCryptoManifestHash,
+    /// <summary><c>manifest_hash_algo_id</c> does not match the binding required by <c>sig_algo_id</c>.</summary>
     HashAlgoBindingMismatch,
+    /// <summary><c>flags</c> carries bits not defined in v1.0.</summary>
     NonZeroFlags,
+    /// <summary><c>signed_count</c> is 0.</summary>
     EmptyManifest,
+    /// <summary><c>trailer_length</c> is non-zero (reserved in v1.0).</summary>
     NonZeroTrailer,
+    /// <summary>A SignedEntry's reserved span is non-zero.</summary>
     NonZeroEntryReserved,
+    /// <summary>A SignedEntry's <c>data_hash_algo_id</c> is not cryptographic (spec Section 9).</summary>
     NonCryptoEntryHash,
+    /// <summary>A SignedEntry references the PCF NIL UID.</summary>
     EntryNilUid,
+    /// <summary>A SignedEntry uses PCF reserved type <c>0x00000000</c>.</summary>
     EntryReservedType,
+    /// <summary>Two SignedEntry records share the same uid.</summary>
     DuplicateSignedUid,
+    /// <summary>A SignedEntry references the enclosing PCFSIG_SIG partition's own uid.</summary>
     SelfSignedEntry,
+    /// <summary>A truncation, short read, or length-field mismatch in the partition payload.</summary>
     MalformedSignaturePartition,
+    /// <summary>Length of <c>sig_bytes</c> does not match the algorithm's natural size.</summary>
     SignatureLengthMismatch,
+    /// <summary>The Writer was asked to sign a partition whose <c>data_hash_algo_id</c> is not cryptographic.</summary>
     NonCryptoTargetHash,
+    /// <summary>The Writer was asked to sign a partition that does not exist in the supplied container.</summary>
     TargetPartitionMissing,
 }
 
 /// <summary>All ways a PCF-SIG operation can fail.</summary>
 public sealed class PcfSigException : Exception
 {
+    /// <summary>The kind of failure.</summary>
     public PcfSigErrorKind Kind { get; }
 
+    /// <summary>Construct an exception of the given kind with the given message.</summary>
     public PcfSigException(PcfSigErrorKind kind, string message)
         : base(message)
     {
         Kind = kind;
     }
 
+    /// <summary>Construct a <see cref="PcfSigErrorKind.BadKeyMagic"/> exception.</summary>
     public static PcfSigException BadKeyMagic() =>
         new(PcfSigErrorKind.BadKeyMagic, "bad PCFSIG_KEY magic");
 
+    /// <summary>Construct a <see cref="PcfSigErrorKind.BadManifestMagic"/> exception.</summary>
     public static PcfSigException BadManifestMagic() =>
         new(PcfSigErrorKind.BadManifestMagic, "bad PCFSIG_SIG manifest magic");
 
+    /// <summary>Construct an <see cref="PcfSigErrorKind.UnsupportedMajor"/> exception.</summary>
     public static PcfSigException UnsupportedMajor(int v) =>
         new(PcfSigErrorKind.UnsupportedMajor, $"unsupported PCF-SIG major version {v}");
 
+    /// <summary>Construct an <see cref="PcfSigErrorKind.UnknownKeyFormat"/> exception.</summary>
     public static PcfSigException UnknownKeyFormat(int id) =>
         new(PcfSigErrorKind.UnknownKeyFormat, $"unknown key_format_id {id}");
 
+    /// <summary>Construct an <see cref="PcfSigErrorKind.EmptyKeyData"/> exception.</summary>
     public static PcfSigException EmptyKeyData() =>
         new(PcfSigErrorKind.EmptyKeyData, "key_data_length is zero");
 
+    /// <summary>Construct a <see cref="PcfSigErrorKind.NonZeroKeyReserved"/> exception.</summary>
     public static PcfSigException NonZeroKeyReserved() =>
         new(PcfSigErrorKind.NonZeroKeyReserved, "key record reserved bytes are non-zero");
 
+    /// <summary>Construct a <see cref="PcfSigErrorKind.FingerprintMismatch"/> exception.</summary>
     public static PcfSigException FingerprintMismatch() =>
         new(PcfSigErrorKind.FingerprintMismatch,
             "stored key fingerprint does not match SHA-256(key_data)");
 
+    /// <summary>Construct an <see cref="PcfSigErrorKind.UnknownSigAlgo"/> exception.</summary>
     public static PcfSigException UnknownSigAlgo(int id) =>
         new(PcfSigErrorKind.UnknownSigAlgo, $"unknown or reserved sig_algo_id {id}");
 
+    /// <summary>Construct a <see cref="PcfSigErrorKind.NonCryptoManifestHash"/> exception.</summary>
     public static PcfSigException NonCryptoManifestHash(int id) =>
         new(PcfSigErrorKind.NonCryptoManifestHash,
             $"manifest_hash_algo_id {id} is not cryptographic");
 
+    /// <summary>Construct a <see cref="PcfSigErrorKind.HashAlgoBindingMismatch"/> exception.</summary>
     public static PcfSigException HashAlgoBindingMismatch() =>
         new(PcfSigErrorKind.HashAlgoBindingMismatch,
             "manifest_hash_algo_id does not match the binding required by sig_algo_id");
 
+    /// <summary>Construct a <see cref="PcfSigErrorKind.NonZeroFlags"/> exception.</summary>
     public static PcfSigException NonZeroFlags() =>
         new(PcfSigErrorKind.NonZeroFlags, "manifest flags are non-zero in v1.0");
 
+    /// <summary>Construct an <see cref="PcfSigErrorKind.EmptyManifest"/> exception.</summary>
     public static PcfSigException EmptyManifest() =>
         new(PcfSigErrorKind.EmptyManifest, "manifest signed_count is 0");
 
+    /// <summary>Construct a <see cref="PcfSigErrorKind.NonZeroTrailer"/> exception.</summary>
     public static PcfSigException NonZeroTrailer() =>
         new(PcfSigErrorKind.NonZeroTrailer, "trailer_length is non-zero in v1.0");
 
+    /// <summary>Construct a <see cref="PcfSigErrorKind.NonZeroEntryReserved"/> exception.</summary>
     public static PcfSigException NonZeroEntryReserved() =>
         new(PcfSigErrorKind.NonZeroEntryReserved,
             "SignedEntry reserved span contains non-zero bytes");
 
+    /// <summary>Construct a <see cref="PcfSigErrorKind.NonCryptoEntryHash"/> exception.</summary>
     public static PcfSigException NonCryptoEntryHash(int id) =>
         new(PcfSigErrorKind.NonCryptoEntryHash,
             $"SignedEntry data_hash_algo_id {id} is not cryptographic");
 
+    /// <summary>Construct an <see cref="PcfSigErrorKind.EntryNilUid"/> exception.</summary>
     public static PcfSigException EntryNilUid() =>
         new(PcfSigErrorKind.EntryNilUid, "SignedEntry uses the NIL UID");
 
+    /// <summary>Construct an <see cref="PcfSigErrorKind.EntryReservedType"/> exception.</summary>
     public static PcfSigException EntryReservedType() =>
         new(PcfSigErrorKind.EntryReservedType,
             "SignedEntry uses PCF reserved type 0x00000000");
 
+    /// <summary>Construct a <see cref="PcfSigErrorKind.DuplicateSignedUid"/> exception.</summary>
     public static PcfSigException DuplicateSignedUid() =>
         new(PcfSigErrorKind.DuplicateSignedUid, "duplicate uid in manifest");
 
+    /// <summary>Construct a <see cref="PcfSigErrorKind.SelfSignedEntry"/> exception.</summary>
     public static PcfSigException SelfSignedEntry() =>
         new(PcfSigErrorKind.SelfSignedEntry,
             "SignedEntry references the PCFSIG_SIG partition itself");
 
+    /// <summary>Construct a <see cref="PcfSigErrorKind.MalformedSignaturePartition"/> exception.</summary>
     public static PcfSigException MalformedSignaturePartition() =>
         new(PcfSigErrorKind.MalformedSignaturePartition,
             "PCFSIG_SIG partition layout is malformed");
 
+    /// <summary>Construct a <see cref="PcfSigErrorKind.SignatureLengthMismatch"/> exception.</summary>
     public static PcfSigException SignatureLengthMismatch() =>
         new(PcfSigErrorKind.SignatureLengthMismatch,
             "sig_bytes length does not match the algorithm");
 
+    /// <summary>Construct a <see cref="PcfSigErrorKind.NonCryptoTargetHash"/> exception.</summary>
     public static PcfSigException NonCryptoTargetHash() =>
         new(PcfSigErrorKind.NonCryptoTargetHash,
             "cannot sign a partition whose data_hash_algo_id is not cryptographic");
 
+    /// <summary>Construct a <see cref="PcfSigErrorKind.TargetPartitionMissing"/> exception.</summary>
     public static PcfSigException TargetPartitionMissing() =>
         new(PcfSigErrorKind.TargetPartitionMissing,
             "partition to sign is not present in the container");

implementations/dotnet/pcf-sig/src/Pcf.Sig/SigAlgo.cs

@@ -92,6 +92,7 @@ public enum KeyFormat : byte
 /// <summary>Registry behaviour for <see cref="KeyFormat"/>.</summary>
 public static class KeyFormatExtensions
 {
+    /// <summary>Map a registry id byte to a key format.</summary>
     public static KeyFormat FromId(byte id)
     {
         switch (id)
@@ -105,7 +106,9 @@ public static KeyFormat FromId(byte id)
         }
     }
 
+    /// <summary>The registry id byte for this format.</summary>
     public static byte Id(this KeyFormat f) => (byte)f;
 
+    /// <summary>Whether this library can extract a verification key from records of this format.</summary>
     public static bool IsImplemented(this KeyFormat f) => f == KeyFormat.Ed25519Raw;
 }

implementations/dotnet/pcf-sig/src/Pcf.Sig/SignaturePartition.cs

@@ -8,9 +8,19 @@ namespace Pcf.Sig;
 /// </summary>
 public sealed class SignaturePartition
 {
+    /// <summary>Parsed Manifest.</summary>
     public Manifest Manifest { get; set; }
+
+    /// <summary>
+    /// Raw bytes of the Manifest as serialised in the partition. This is the
+    /// signing input and MUST be byte-exact, so the parser caches it.
+    /// </summary>
     public byte[] ManifestBytes { get; set; }
+
+    /// <summary>Raw signature bytes (the algorithm's natural output).</summary>
     public byte[] Signature { get; set; }
+
+    /// <summary>Trailer bytes; MUST be empty in v1.0.</summary>
     public byte[] Trailer { get; set; } = new byte[0];
 
     /// <summary>Compose a partition payload from a manifest + signature.</summary>

implementations/dotnet/pcf-sig/src/Pcf.Sig/SigningMaterial.cs

@@ -11,9 +11,15 @@ namespace Pcf.Sig;
 /// </summary>
 public sealed class SigningMaterial
 {
+    /// <summary>The signature algorithm id this signer produces.</summary>
     public SigAlgo SigAlgo { get; }
+
+    /// <summary>The key format id of the signer's public material.</summary>
     public KeyFormat KeyFormat { get; }
+
+    /// <summary>The signer's public key bytes in the encoding named by <see cref="KeyFormat"/>.</summary>
     public byte[] PublicKeyBytes { get; }
+
     private readonly byte[] _secretSeed;
 
     private SigningMaterial(SigAlgo sigAlgo, KeyFormat keyFormat, byte[] secretSeed, byte[] publicKeyBytes)