Skip to content

docs: add doc-test examples for public API functions#149

Merged
EffortlessSteven merged 1 commit into
mainfrom
wave-111/doc-tests
Mar 2, 2026
Merged

docs: add doc-test examples for public API functions#149
EffortlessSteven merged 1 commit into
mainfrom
wave-111/doc-tests

Conversation

@EffortlessSteven

@EffortlessSteven EffortlessSteven commented Mar 2, 2026

Copy link
Copy Markdown
Member

Summary

Adds /// # Examples doc-test sections to all public API items that were missing them across the user-facing crates.

Changes

Crates updated (12 files, ~1108 lines added):

  • uselesskey-rsa (keypair.rs, spec.rs) — 13 doc examples for write_*, corrupt_deterministic, JWK methods, stable_bytes
  • uselesskey-ecdsa (keypair.rs, spec.rs) — 17 doc examples for spec(), write_*, corrupt_deterministic, JWK methods, alg_name, curve_name, coordinate_len_bytes, stable_bytes
  • uselesskey-ed25519 (keypair.rs, spec.rs) — 15 doc examples for write_*, corrupt_deterministic, JWK methods, new(), stable_bytes
  • uselesskey-hmac (secret.rs) — 3 doc examples for kid, jwk, jwks
  • uselesskey-core-hmac-spec (lib.rs) — 6 doc examples for hs256/hs384/hs512, alg_name, byte_len, stable_bytes
  • uselesskey-x509 (cert.rs, chain.rs, chain_negative.rs, negative.rs) — 40+ doc examples for all cert/chain accessors, write_* methods, negative fixtures, CRL methods

Conventions:

  • RSA and X509 doc tests use no_run (slow RSA keygen)
  • ECDSA, Ed25519, HMAC, Token use runnable examples
  • Setup code is hidden with # prefix
  • JWK methods are feature-gated with #[cfg(feature = "jwk")]

Verification

  • cargo fmt --all — clean
  • cargo clippy --workspace --all-features --tests -- -D warnings — 0 warnings
  • cargo test --doc --workspace --all-features --exclude uselesskey-bdd — all pass (0 failures)

@gemini-code-assist

gemini-code-assist Bot commented Mar 2, 2026

Copy link
Copy Markdown

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

@coderabbitai

coderabbitai Bot commented Mar 2, 2026 •
edited
Loading

Copy link
Copy Markdown

Warning

Rate limit exceeded

@EffortlessSteven has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 28 minutes and 25 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 52c892c and 6f6735a.

📒 Files selected for processing (12)
  • crates/uselesskey-core-hmac-spec/src/lib.rs
  • crates/uselesskey-ecdsa/src/keypair.rs
  • crates/uselesskey-ecdsa/src/spec.rs
  • crates/uselesskey-ed25519/src/keypair.rs
  • crates/uselesskey-ed25519/src/spec.rs
  • crates/uselesskey-hmac/src/secret.rs
  • crates/uselesskey-rsa/src/keypair.rs
  • crates/uselesskey-rsa/src/spec.rs
  • crates/uselesskey-x509/src/cert.rs
  • crates/uselesskey-x509/src/chain.rs
  • crates/uselesskey-x509/src/chain_negative.rs
  • crates/uselesskey-x509/src/negative.rs

Walkthrough

This PR comprehensively adds documentation examples and usage blocks across multiple cryptography-related crates (HMAC, ECDSA, Ed25519, RSA, X.509) without modifying any functional code, control flow, or public API signatures. All changes are purely documentation additions totaling 1,161+ lines.

Changes

Cohort / File(s) Summary
HMAC Specifications
crates/uselesskey-core-hmac-spec/src/lib.rs, crates/uselesskey-hmac/src/secret.rs		 Added documentation examples to HmacSpec constructors and methods (alg_name, byte_len, stable_bytes), plus JWK methods on HmacSecret.
ECDSA Specifications and KeyPair
crates/uselesskey-ecdsa/src/spec.rs, crates/uselesskey-ecdsa/src/keypair.rs		 Added doc examples to EcdsaSpec methods and EcdsaKeyPair serialization, JWK, PKCS#8, and SPKI methods.
Ed25519 Specifications and KeyPair
crates/uselesskey-ed25519/src/spec.rs, crates/uselesskey-ed25519/src/keypair.rs		 Added doc examples to Ed25519Spec and Ed25519KeyPair methods covering PKCS#8, SPKI, JWK serialization, and deterministic corruption variants.
RSA Specifications and KeyPair
crates/uselesskey-rsa/src/spec.rs, crates/uselesskey-rsa/src/keypair.rs		 Added documentation examples to RsaSpec stable_bytes and RsaKeyPair serialization, JWK, and corruption methods.
X.509 Certificates and Chains
crates/uselesskey-x509/src/cert.rs, crates/uselesskey-x509/src/chain.rs, crates/uselesskey-x509/src/chain_negative.rs, crates/uselesskey-x509/src/negative.rs		 Added comprehensive doc examples to X.509 certificate and chain methods covering PEM/DER serialization, negative test fixtures, CRL handling, and metadata accessors.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Possibly related PRs

Poem

🐰 Docstrings bloom like carrots in spring,
Examples and notes on each little thing,
No logic was harmed in this verbose display,
Just guidance for users to find their own way! 📖✨

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title accurately describes the primary change: adding documentation examples to public API functions across multiple crates.
Description check ✅ Passed The description comprehensively details what was changed, which crates were updated, conventions used, and verification steps performed.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch wave-111/doc-tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@EffortlessSteven
docs: add doc-test examples for public API functions
6f6735a 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@EffortlessSteven EffortlessSteven merged commit 31c0ea0 into main Mar 2, 2026
3 of 4 checks passed
@coderabbitai coderabbitai Bot mentioned this pull request Mar 3, 2026
Merged
@EffortlessSteven EffortlessSteven deleted the wave-111/doc-tests branch March 5, 2026 15:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@EffortlessSteven