docs: document mandatory .zeroize() call for secret types

[dobby-coder]

What

Documents the zeroization contract for the secret types introduced by #14.

Because SharedSecret, SecretKey and UserSecretKey are Copy, they cannot derive ZeroizeOnDrop (a Copy type cannot implement Drop). With the zeroize feature they only derive Zeroize, so secret material is not wiped automatically on drop — callers MUST call .zeroize() explicitly.

This PR adds the interim documentation requested in #45:

• A # Zeroizing secret material section in the crate-level docs (lib.rs) explaining the contract, with a usage example.
• A # Zeroization MUST-call annotation on every affected public secret type across all KEM and IBE schemes: kem::SharedSecret, the Boyen-Waters IBE SharedSecret, and the SecretKey / UserSecretKey of Waters, Waters-Naccache, Boyen-Waters, CGW, CGW-KV, CGW-FO and Kiltz-Vahlis.

Each per-type note links back to the crate-level section (anchor verified in generated docs).

The Boyen-Waters SharedSecret(Gt) was the one secret type initially left unannotated; Gt implements Zeroize, so it now derives Zeroize and carries the same note as every other secret type — coverage is complete.

Why draft / scope

The actual fix — making these types !Copy so ZeroizeOnDrop can be derived and wiping happens automatically — is a breaking API change deferred to a future major release, per the maintainer note on #45. This PR only adds the interim documentation.

Stacked on #14 (feat/zeroize-secret-types), since it documents the feature that PR introduces. Base will retarget to main automatically once #14 merges.

Testing

• cargo fmt --all -- --check — clean
• cargo build --all-features --lib — clean
• cargo test --all-features — 18 passed (incl. the secret_types_zeroize test from feat: optional zeroize feature for secret types (#7) #14)
• cargo doc --all-features with -D rustdoc::broken_intra_doc_links — clean; the #zeroizing-secret-material anchor and cross-links resolve

Closes #45

🤖 Generated with Claude Code

[dobby-coder]

Rules Dobby 2 — consolidated review. Ran all 80 memory rules via parallel Haiku checks (all compliant) and merged with Review Dobby 2's findings. Docs build clean, --all-features suite passed. One non-blocking accuracy nit on the PR's scope claim.

Finding (nit — promised-vs-delivered): src/ibe/boyen_waters.rs:94 — the PR description states it annotates every SharedSecret across all KEM & IBE schemes, but boyen_waters::SharedSecret(Gt) (a public secret type whose bytes derive an AES key) received neither the # Zeroization doc section nor a Zeroize derive. This is arguably intentional/out-of-scope: the crate-level docs scope SharedSecret to crate::kem::SharedSecret (the KEMs), and this type does not derive Zeroize, so there is no .zeroize() to document. It is also pre-existing (predates this PR). Not blocking — the cleanest resolution is to narrow the PR-description claim (or add a one-line note that boyen_waters::SharedSecret is intentionally excluded because it is not Zeroize).

(Anchored in the body rather than inline: line 94 is outside this PR's diff hunks, so an inline comment there would be rejected by the reviews API.)

[dobby-coder]

Addressed the scope nit in ba2458c. Rather than narrowing the description, I annotated the one remaining secret type: boyen_waters::SharedSecret(Gt). Gt implements Zeroize, so the type now derives Zeroize and carries the same # Zeroization note as every other secret type — the "every affected public secret type" claim is now literally true. Crate-level docs sentence broadened to name the Boyen-Waters IBE SharedSecret alongside the KEM one.

Re-verified: cargo fmt --check, cargo build --all-features --lib, cargo test --all-features (18 passed), and cargo doc --all-features with -D rustdoc::broken_intra_doc_links all clean.