docs: complete the public API documentation contract

Closes the last open item in #25. `cargo clippy -W missing_errors_doc
-W missing_panics_doc -W must_use_candidate -W doc_markdown` went from 56
warnings to zero.

The 13 hand-written sections name the actual variants each function returns
rather than gesturing at "an error". Establishing that meant reading the error
paths — `Game::ranked` alone returns four distinct variants, and `record_draw`
can hit TieWithoutDrawProbability where `record_winner` provably cannot, since
a two-team decisive outcome has nothing to tie. Documenting those as
interchangeable would have been worse than leaving them undocumented, because
a reader would trust it.

Two existing doc comments already described panics in prose but not under a
`# Panics` heading, so neither rustdoc nor clippy surfaced them:
`Outcome::winner` and `EventBuilder::weights`. Both now carry the heading, and
`Outcome::winner` gained the note that it ties every loser, so `n >= 3` needs a
positive p_draw — the crate's easiest error to hit by accident.

The 43 mechanical fixes (31 `#[must_use]` on pure accessors, 11 missing
backticks) were applied with `cargo clippy --fix`. `#[must_use]` on Gaussian's
arithmetic and on `posteriors()` matters: discarding those results is always a
bug, and until now nothing said so.

Also documented why `[profile.release] debug = true` exists — cargo-flamegraph
needs the symbols, and library profile settings are ignored downstream, so it
reads as an oversight without the note.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T5SYDExxL4vZgvunrcNSMc

src/factor/margin.rs

@@ -20,6 +20,7 @@ pub struct MarginFactor {
 }
 
 impl MarginFactor {
+    #[must_use]
     pub fn new(diff: VarId, m_obs: f64, sigma: f64) -> Self {
         debug_assert!(sigma > 0.0, "score sigma must be positive");
         Self {

src/factor/mod.rs

@@ -20,6 +20,7 @@ pub struct VarStore {
 }
 
 impl VarStore {
+    #[must_use]
     pub fn new() -> Self {
         Self::default()
     }
@@ -28,10 +29,12 @@ impl VarStore {
         self.marginals.clear();
     }
 
+    #[must_use]
     pub fn len(&self) -> usize {
         self.marginals.len()
     }
 
+    #[must_use]
     pub fn is_empty(&self) -> bool {
         self.marginals.is_empty()
     }
@@ -42,6 +45,7 @@ impl VarStore {
         id
     }
 
+    #[must_use]
     pub fn get(&self, id: VarId) -> Gaussian {
         self.marginals[id.0 as usize]
     }

src/factor/rank_diff.rs

@@ -5,12 +5,12 @@ use crate::factor::{Factor, VarId, VarStore};
 /// On each propagation:
 /// - Reads marginals at `team_a` and `team_b` (which already incorporate any
 ///   incoming messages from neighboring factors).
-/// - Computes `new_diff = team_a - team_b` (variance addition; see Gaussian::Sub).
+/// - Computes `new_diff = team_a - team_b` (variance addition; see `Gaussian::Sub`).
 /// - Writes the new marginal to `diff`.
 /// - Returns the delta against the previous diff value.
 ///
 /// This factor does NOT store an outgoing message; the diff variable is
-/// effectively replaced on each propagation. The TruncFactor on the same diff
+/// effectively replaced on each propagation. The `TruncFactor` on the same diff
 /// var holds the EP-divide message that produces the cavity.
 #[derive(Debug)]
 pub struct RankDiffFactor {

src/factor/trunc.rs

@@ -15,13 +15,14 @@ pub struct TruncFactor {
     pub diff: VarId,
     pub margin: f64,
     pub tie: bool,
-    /// Outgoing message to the diff variable (initial: N_INF, the EP identity).
+    /// Outgoing message to the diff variable (initial: `N_INF`, the EP identity).
     pub(crate) msg: Gaussian,
     /// Cached evidence (linear, not log) computed from the cavity on first propagation.
     pub(crate) evidence_cached: Option<f64>,
 }
 
 impl TruncFactor {
+    #[must_use]
     pub fn new(diff: VarId, margin: f64, tie: bool) -> Self {
         Self {
             diff,