docs: document public mutating contract endpoints (#355)

[psalmuel3]

Summary

dongle-smartcontract/src/lib.rs declares 464 public DongleContract functions; only 252 of them carried a doc comment, and none of the core flows named in the issue (register_project, update_project, add_review, request_verification, set_fee, pay_fee) did. Because CONTRACT_INTERFACE.md is maintained by hand in a separate file, every undocumented entry point is a place where the contract can drift away from its published interface.

This PR adds /// doc comments to 107 public endpoints — the complete mutating/state-changing surface — with 868 added lines and 0 removed. Each comment documents what the function does, its parameters, its preconditions, the authorization the body actually enforces, the state it writes, and the errors/panics it can raise (traced to concrete ContractError variants). No executable code, no existing comment, and no existing formatting was touched.

Notable endpoints now documented, with their auth model

Endpoint	Authorization enforced by the code
register_project	params.owner must sign (self-auth); owner must be under the active-project cap; not paused
update_project	caller must sign and be the project owner or a registered maintainer; verify-state fields frozen
add_review	reviewer must sign; project owner/maintainers are rejected; anti-sybil eligibility rules apply
request_verification	owner-only — requester must sign and equal the project owner (maintainers and admins cannot request)
set_fee	admin-only (require_admin_auth); rejected with Unauthorized while the admin approval threshold is > 1
pay_fee	owner-only — payer must sign and equal the project owner; token must match the configured fee token
create_proposal	proposer must sign and be a registered admin; recorded as first approval; auto-approved at threshold 1
schedule_* / timelock ops	admin-only; most reject while the approval threshold is > 1
collection ops (add_ccol_curator, remove_ccol_curator, …)	collection creator-only after a require_self_auth, with curator/creator roles distinguished
process_verification_expiry, process_expiry_notification	permissionless — no Address argument, no require_auth, not pause-gated
record_expiry_notification_sent	admin-only (require_admin_auth)

Two categories worth calling out, because they are exactly the "non-obvious auth semantics" the issue asks for:

• Multisig-gated admin operations. Several admin endpoints are documented as refusing (ContractError::Unauthorized) while admin_approval_threshold > 1, directing the caller through create_proposal → approve_proposal → execute_proposal instead.
• Caller comparisons without require_auth. A few helpers (for example cancel_fee_payment and approve_contract_claim) compare an explicitly supplied caller/payer against stored state but never call require_auth on that address. Rather than invent an auth rule, the doc comment states the comparison that is actually performed and flags that the address is not signature-checked. This is existing behaviour, not a change made here.

Note on the earlier attempt

An earlier PR from the same contributor, #457 ("docs: document public mutation endpoints", +216 lines), was closed unmerged on 2026-09-23 without review comments. The documentation is still missing on main, so this is a fresh change written directly against current main — not a rebase or resurrection of that branch — and it covers a substantially larger part of the surface (107 endpoints / 868 lines).

Verification

Toolchain: cargo 1.99.0 (rustup toolchain 1.99.0-x86_64-apple-darwin) and rustfmt 1.8.0-stable, both via export PATH="$HOME/.cargo/bin:$PATH", run from the workspace root.

1. cargo +1.99.0 check -p dongle-contract — exit 101, 334 errors on this branch, and 334 errors on a pristine upstream main checkout. Normalising both logs to (error code, message) and sorting by frequency, the signature sets are identical; both also produce zero warnings. The pre-existing parse diagnostic is the same message ("expected ;, found keyword pub") at the same source position, and the edited file does not shift it.

2. cargo check -p dongle-contract (active toolchain 1.85.0) — same picture: exit 101, 335 errors on both the branch and pristine main, with identical normalised signature sets.

3. cargo fmt --check --all — fails, but with the same pre-existing parse error on lib.rs (expected ;, found keyword pub``), so rustfmt cannot lint this crate at all on main either. To verify the additions themselves are format-clean I ran `rustfmt --edition 2021 --check` on a synthetic file holding real doc blocks from this change attached to stub functions: exit 0, no diff.

4. Diff-is-comment-only proof — a difflib unified diff of the pristine lib.rs (fetched from upstream main) against this branch reports 868 added, 0 removed, and every added line matches ^\s*//. Stripping every comment line from both files yields identical line sequences, which proves no executable line and no existing comment was modified or reordered.

Caveats

• cargo check cannot pass on this repository (upstream main itself is broken), so the change is validated by differential diagnostics under two toolchains (1.99.0 and 1.85.0) rather than a green build; identical error and warning sets across both are the strongest available evidence that comment-only edits changed nothing semantically.
• 105 public functions remain undocumented, and all of them are read-only accessors/getters (get_*, is_*, list_*, has_*, compare_*, export_*), so they are outside the "mutating endpoints" scope of the issue. A follow-up could cover the read surface.
• Broken intra-doc links only warn, but I avoided [Bracketed] reference links entirely, so no new rustdoc warnings are introduced.

Closes #355

[psalmuel3]

@ReinaMaze Documentation for the public mutating endpoints in dongle-smartcontract/src/lib.rs, as requested in #355.

• 107 mutating endpoints documented, taking the file from 252 to 359 of its 464 pub fns. Read-only getters were intentionally left for a follow-up to keep this reviewable.
• Each doc comment records the parameters, the authorization actually enforced, the state changed, and the failure conditions, traced from the function bodies rather than restated from CONTRACT_INTERFACE.md. Auth models are called out explicitly, for example register_project (owner self-auth), update_project (owner or registered maintainer), request_verification (owner-only, maintainers cannot act on the owner's behalf), set_fee (admin-only, rejected while the approval threshold is > 1), pay_fee (owner-only, token must match the configured fee token), and the permissionless process_verification_expiry / process_expiry_notification.
• Comment-only change: +868 / -0. No executable line is modified, which I verified independently by stripping comments from before and after and confirming the remaining code is identical.

Verification caveat, stated plainly: cargo check already reports 335 errors on main (there is a pre-existing parse break in this file), so a green build is not reachable here. I compared diagnostics against pristine main and the set is identical, with no new or removed diagnostics, and rustfmt --check is clean on the added doc blocks.

Also worth flagging: this is a fresh change against current main; the earlier PR #457 for this issue was closed unmerged with no review, so it should not be resurrected. Thanks!