Skip to content

docs: add XML documentation for security utility factories (Batch 6)#674

Open
KonradSop wants to merge 1 commit intobcgit:masterfrom
KonradSop:feature/utility-factories-docs
Open

docs: add XML documentation for security utility factories (Batch 6)#674
KonradSop wants to merge 1 commit intobcgit:masterfrom
KonradSop:feature/utility-factories-docs

Conversation

@KonradSop
Copy link
Copy Markdown
Contributor

Description

Adds XML documentation to the six user-facing factory entry points under crypto/src/security. These classes are the primary discovery surface for callers who reach for an algorithm by name (JCA-style) rather than by direct type, and previously carried little or no API documentation.

  • CipherUtilities — class summary describing the ALGORITHM[/MODE[/PADDING]] convention, plus <summary>/<param>/<returns>/<exception> for GetAlgorithmName and both GetCipher overloads.
  • DigestUtilities — factory and one-shot helpers: all CalculateDigest, DoFinal overloads, GetAlgorithmName, GetDigest(string), GetDigest(DerObjectIdentifier), GetObjectIdentifier. Removed a stray duplicate <param name="mechanism"> block that emitted CS1571.
  • MacUtilities — class summary noting required initialization, plus CalculateMac, both DoFinal overloads, GetAlgorithmName, GetMac(string), GetMac(DerObjectIdentifier).
  • SignerUtilities — class summary covering the DIGESTwithCIPHER convention, plus Algorithms, GetDefaultX509Parameters (both), GetEncodingName, GetSigner (both), InitSigner (both, with full parameter docs).
  • GeneratorUtilitiesGetKeyGenerator (both), GetKeyPairGenerator (both).
  • ParameterUtilitiesGetCanonicalAlgorithmName, all four CreateKeyParameter overloads, both GetCipherParameters, both GenerateParameters, plus the ParametersWithRandom / ParametersWithContext envelope helpers (GetContext, GetRandom, IgnoreRandom, WithContext, WithRandom).

Key Accomplishments

  • Discoverability: Class-level summaries explain the JCA-style naming convention each factory accepts, so IDE tooltips give callers a complete mental model from one hover.
  • Accurate exception contracts: <exception> tags only added where the method body actually throws — no speculative annotations.
  • Implementation comments preserved: All pre-existing // TODO[api], // TODO, and inline implementation notes left verbatim.
  • Consistent style: 120-char line limit applied across all six files; <see cref="..."/> used for type/member references rather than backticks.

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.

Document the six public factory entry points under crypto/src/security:
CipherUtilities, DigestUtilities, MacUtilities, SignerUtilities,
GeneratorUtilities, and ParameterUtilities. Adds class-level summaries
describing the JCA-style algorithm-name conventions and per-method
<summary>, <param>, <returns>, and <exception> tags for the public API
surface. 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