[definurse13]

Closes #3

Adds /// documentation to the public items that were missing it across all four crates — 47 of the 182 public items — and makes cargo doc warning-free, which it was not before this change.

Every added comment states what the function returns, what its arguments mean where it takes any, and whether it can fail.

The part worth reviewing: what zero means

Most of the gap was view helpers, and for nearly all of them the ambiguous case is the zero value. Documenting "returns the buyer limit" would have been useless; documenting what 0 means is the thing a caller actually needs:

• buyer_limit_bps, sme_limit_bps, min_deposit, max_deposit, reserve_ratio_bps return 0 when create_pool has not run. That is unconfigured, not a limit of zero — a caller reading it as the latter draws exactly the wrong conclusion.
• withdraw_util_threshold defaults to BPS_SCALE, not 0, because the permissive default is the one where utilisation never blocks a withdrawal.
• nav defaults to NAV_SCALE — parity — not zero.
• is_upgrade_paused returning true does not mean nothing is pending: queueing and cancelling still work while paused, and only the Wasm swap is held back.
• invoice_due_at returning None means the grace-period clock has never started, so the invoice cannot be defaulted at all — a materially different state from "due, but not yet".

Fixing cargo doc (acceptance criterion 3)

cargo doc was emitting 10 unresolved-link warnings before this change, so the criterion could not be met just by adding comments.

All ten were [`Self::foo`] references inside #[contractimpl] blocks. The macro expands each function into its own __foo module, so Self does not resolve to the contract type from inside the generated docs, and every such link silently breaks — they render as plain text rather than links, which is why this went unnoticed.

Rewriting them as fully-qualified paths (PoolManager::foo, InvoiceRegistry::foo, and so on) resolves them against the contract struct, so the links now actually work rather than being dropped. New doc comments use the same form for the same reason.

cargo doc --workspace --no-deps is now clean: 0 warnings.

Also

Public struct fields on WaterfallTier, WaterfallResult and QueuedUpgrade are documented, and QueuedUpgrade's header was // rather than /// — so it never reached the docs at all. That is now fixed.

Acceptance criteria

• Parameters and return values described
• Errors/panics documented
• cargo doc warning-free (was 10 warnings, now 0)

No behaviour change

Comments only, plus one doc comment split so two storage constants each carry their own rather than sharing one. No signature, no logic, no manifest touched.

Verification

cargo check --workspace, cargo test --workspace, cargo doc --workspace --no-deps (0 warnings), and cargo build --release --target wasm32-unknown-unknown --workspace all pass.

This PR and #7 are conflict-free in either merge order. They touch disjoint file sets by construction — this one only .rs files, #7 only Cargo.toml files. I merged them both ways locally against main to confirm rather than assume: zero conflicts each way, both orders produce an identical tree, and the merged result passes the full gate. Whichever you merge first, the other needs no rebase.

[codemagician1949]

@definurse13 please fix failing ci