Skip to content

docs: add XML documentation for ML-KEM and ML-DSA parameter gaps (Batch 9)#679

Open
KonradSop wants to merge 1 commit intobcgit:masterfrom
KonradSop:feature/ml-pqc-gaps-docs
Open

docs: add XML documentation for ML-KEM and ML-DSA parameter gaps (Batch 9)#679
KonradSop wants to merge 1 commit intobcgit:masterfrom
KonradSop:feature/ml-pqc-gaps-docs

Conversation

@KonradSop
Copy link
Copy Markdown
Contributor

Closes the documentation gaps left by PR #673 (Batch 5, ML-KEM and ML-DSA initial pass). PR #673 covered MLKemParameters, MLKemPublicKeyParameters, MLKemPrivateKeyParameters, MLDsaParameters and MLDsaPublicKeyParameters; this PR documents the remaining seven public types so the FIPS 203 / FIPS 204 surface is consistent.

  • MLKemParameterSet — class summary citing FIPS 203; per-constant summaries naming each parameter set (NIST Category 1/3/5, module rank k); doc on EncapsulationLength, SecretLength, Name, ToString.
  • MLKemKeyParameters — abstract base; class summary plus Parameters accessor doc.
  • MLKemKeyGenerationParameters — class summary covering the SecureRandom + parameter-set pairing and the strength = 0 rationale; both constructors document their ArgumentNullException / ArgumentException contracts.
  • MLDsaParameterSet — class summary citing FIPS 204; per-constant summaries (NIST Category 2/3/5, modes 2/3/5); doc on Name, ToString.
  • MLDsaKeyParameters — abstract base; class summary plus Parameters accessor doc.
  • MLDsaKeyGenerationParameters — same shape as the ML-KEM counterpart; OID-lookup constructor exception text notes both pure and HashML-DSA OIDs are accepted.
  • MLDsaPrivateKeyParameters — class summary explaining the (ρ, K, tr, s₁, s₂, t₀) expansion plus cached t₁. Format enum documented per value (SeedOnly, EncodingOnly, SeedAndEncoding). FromEncoding, both FromSeed overloads, GetEncoded, GetPublicKey, GetPublicKeyEncoded, GetSeed, PreferredFormat, WithPreferredFormat documented with their full exception contracts.

Key Accomplishments

  • Closes Batch 5 holes: completes the FIPS 203 / FIPS 204 documentation surface that PR docs: add XML documentation for ML-KEM and ML-DSA parameters (Batch 5) #673 left half-finished. ML-KEM and ML-DSA now match the depth of coverage given to SLH-DSA in Batch 8.
  • Accurate exception contracts: <exception> tags only added where the method body actually throws — ArgumentNullException / ArgumentException on FromEncoding, FromSeed and OID-lookup paths; InvalidOperationException on WithPreferredFormat when a seed is required but unavailable.
  • Consistent style: Class summaries follow the Batch 5 / Batch 8 PQC-params pattern (FIPS reference, what is wrapped, decoding contract). Internal members and pre-existing implementation comments left untouched.
  • No overlap with open PRs: scope is disjoint from feature/modern-curves-docs (Batch 7) and feature/slh-dsa-docs (Batch 8) — each of the seven files in this PR is untouched by either branch.

Verification

  • Build Status: dotnet build crypto/src/BouncyCastle.Crypto.csproj -c Release — succeeded on net6.0, netstandard2.0, net461 with no new warnings.
  • Scope: Documentation-only; no behavioural or signature changes.

Checklist before requesting a review

  • I have performed a self-review of my code
  • I have kept the patch limited to only change the parts related to the patch
  • This change requires a documentation update

See also Contributing Guidelines.

Closes the documentation gaps left by the initial ML-KEM/ML-DSA
documentation pass. Adds class-level summaries citing FIPS 203 / FIPS 204
and per-method <summary>, <param>, <returns>, and <exception> tags for
the public API surface of MLKemParameterSet, MLKemKeyParameters,
MLKemKeyGenerationParameters, MLDsaParameterSet, MLDsaKeyParameters,
MLDsaKeyGenerationParameters, and MLDsaPrivateKeyParameters (including
the Format enum and seed/encoding helpers). No behavioural changes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant