Add rustdoc comments to all public items

[cedoor]

Summary

Bring all public items in squid up to a publishable rustdoc baseline: every type, method, field, re-export, and module documented, with runnable examples on the items users actually call. The rendered docs (docs.rs / cargo doc --open) should be enough to write a working program without reading source.

Motivation

squid is the user-facing front for Poulpy's bdd_arithmetic. Most consumers will not read Poulpy source — they will land on docs.rs and decide in 30 seconds whether the crate is usable. Today the docs are partial:

• No crate-level overview in src/lib.rs — docs.rs landing page is empty.
• Public re-exports of Poulpy types (GLWESecret, LWESecret, BDDKey, CGGI) appear undocumented in our docs (src/lib.rs:10-12).
• KeygenSeeds exposes three pub fields with no per-field docs (src/keys.rs:47-51).
• Most methods have prose but no # Examples block — users have to assemble the call sequence from scattered references.

Work

1. Crate-level overview in lib.rs

Add a //! block at the top of src/lib.rs covering: what the crate is, the Context -> keygen -> encrypt -> op -> decrypt flow, the backend-avx feature flag, and a single end-to-end runnable example. Sketch:

//! `squid` is an ergonomic Rust wrapper for the [Poulpy] FHE toolkit.
//!
//! All operations flow through [`Context`]. A typical session:
//!
//! ```rust,no_run
//! use squid::{Context, Params};
//!
//! let mut ctx = Context::new(Params::unsecure());
//! let (sk, ek) = ctx.keygen();
//!
//! let a = ctx.encrypt::<u32>(42, &sk);
//! let b = ctx.encrypt::<u32>(7, &sk);
//! let sum = ctx.add(&a, &b, &ek);
//! assert_eq!(ctx.decrypt::<u32>(&sum, &sk), 49);
//! ```
//!
//! See [`Context`], [`Params`], [`SecretKey`], [`EvaluationKey`], [`Ciphertext`].
//!
//! [Poulpy]: https://github.com/phantomzone-org/poulpy

2. Examples on the high-traffic methods

Add # Examples blocks (compile-checked rust,no_run) to the methods users will reach for first:

• Context::keygen and Context::keygen_with_seeds — show the seed-replay round trip.
• Context::keygen_from_seeds — show that the same seeds reproduce identical keys.
• Context::encrypt / Context::decrypt — show the round trip with one of u8/u16/u32.
• One arithmetic op (e.g. Context::add) — example with a comment that all 10 ops follow the same shape.
• Context::serialize_evaluation_key / Context::deserialize_evaluation_key — show write -> bytes -> read.
• Context::serialize_ciphertext / Context::deserialize_ciphertext — same.
• EvaluationKey::serialize / EvaluationKey::deserialize and Ciphertext::serialize / Ciphertext::deserialize — note these mirror the Context::* ones.
• SecretKey::from_lattice_seed — show pairing with Context::deserialize_evaluation_key to rebuild a session from persisted material.

Example sketch for Context::keygen_with_seeds:

/// # Examples
///
/// ```rust,no_run
/// use squid::{Context, Params};
///
/// let mut ctx = Context::new(Params::unsecure());
/// let (sk, ek, seeds) = ctx.keygen_with_seeds();
///
/// // Persist `seeds` (96 bytes) instead of the full secret key.
/// let (sk2, ek2) = ctx.keygen_from_seeds(seeds);
/// // sk2 / ek2 are bit-identical to sk / ek for these Params.
/// ```

3. Field-level docs on KeygenSeeds

src/keys.rs:47-51 — each of lattice, bdd_mask, bdd_noise should explain which Poulpy Source stream it seeds (lattice secrets, BDD public masks, BDD error). Currently only the struct doc covers this.

4. Re-exports

src/lib.rs:10-12 re-exports GLWESecret, LWESecret, BDDKey, CGGI from Poulpy. Either:

• add a one-line #[doc = "..."] on each re-export explaining why it's surfaced and where it's used in our API, or
• drop the re-export if it isn't actually needed downstream (audit call sites first).

5. Enforce going forward

Once the gaps are filled, add #![deny(missing_docs)] to src/lib.rs so future public items can't slip through without docs.

Acceptance

• cargo doc --no-deps produces a landing page with the elevator pitch and a runnable example.
• cargo test --doc passes (all examples compile; no_run is fine for the keygen-heavy ones).
• cargo doc --no-deps 2>&1 | grep warning is empty (with #![deny(missing_docs)] enabled).
• Spot check on docs.rs preview: a new user can copy the crate-level example and have it compile.

Out of scope

• Long-form guide / mdbook (tracked separately under "Realistic examples" Realistic examples #16).
• Vetted Params presets (Vetted Params presets #18) — we keep unsecure() framing as today.