Documentation volume does not consistently cover failure contracts

Timing: Follow-up after trial/3 merges into main; defer implementation until then.

Review baseline: Local trial/3 at a094418baf6388e3eeca23821df481a7f0a8751c. This branch is not yet on the remote. Source locations below refer to that snapshot and should be rechecked after merge.

Problem

Some public fallible APIs have substantial happy-path examples but omit explicit error conditions. Documentation volume therefore does not consistently tell callers when operations fail or what state is retained after failure.

Evidence

crates/server/src/builder.rs:140-156: plugin_with can reject an invalid specification, duplicate ID, sealed selection, or selection budget, but lacks a # Errors section.
The review's opt-in Clippy pass found similar missing_errors_doc omissions elsewhere.

Acceptance criteria

Review public fallible APIs and document meaningful failure conditions with standard # Errors sections or clear links to shared contracts.
Explain partial mutation, retained state, cancellation, retryability, and error precedence where applicable.
Prefer accurate caller-facing contracts to generic boilerplate or duplicated examples.
Run affected Rustdoc/doctest checks; do not change runtime behavior as part of this documentation task.

Code examples and suggested direction

Suggested Rustdoc for the actual registration-time behavior:

/// Select a compiled plugin with checked presence/order declarations.
///
/// # Errors
///
/// Returns an error for an invalid plugin specification, a duplicate
/// selected ID, selection after sealing, or the selection-count limit.
/// Rejection leaves previously selected plugins unchanged.
///
/// This queues registration; missing dependencies, cycles, ordering
/// violations, and registration-callback failures are reported by
/// ServerBuilder::build, not by this method.

Keep links to the corresponding types/methods as intra-doc links when integrating this text. Recheck each claim against the merged implementation.

Suggested investigation and fix notes

Deferred until trial/3 is merged into main. Recheck the merged source and tests first. The snippets are examples/proposals, not an approved patch or a change to frozen contracts.

Inventory public Result APIs in the touched crate, starting with ServerBuilder::plugin_with. Use missing_errors_doc as a search aid; inspect source rather than copying a generic error sentence everywhere.
Separate immediate registration validation from deferred build-time validation. The example in the description deliberately distinguishes these phases.
For each operation, state failure classes, mutation guarantees, error precedence, cancellation/retry behavior, and feature/platform constraints only where applicable.
Preserve meaningful explanations and working examples required by project style. Link shared contracts instead of copying the same large example into every field.
Keep this change documentation-only. If prose review discovers a behavioral bug, report/link it separately rather than silently changing code under this issue.

Focused discovery and verification:

cargo clippy -p stackpress-server --all-targets --locked -- -W clippy::missing_errors_doc
cargo test -p stackpress-server --doc --locked
RUSTDOCFLAGS="-D warnings" cargo doc -p stackpress-server --no-deps --locked

The opt-in lint can uncover unrelated items; record the reviewed scope instead of enabling all pedantic lints globally. This documentation-only task does not need invented runtime tests or a new executable-coverage claim.

Follow the repository's documentation/style review process and record the checked crate/features. Keep this issue documentation-only.

Partly fixed on trial/3 in 644795f (merged as 64a5b70): the lib portion is done. Accurate `# Errors` sections added for public fallible lib APIs. Server/CLI/transformer parts are in task 00010 lane 2; SQL and framework parts follow in a third pass. Leaving open.

Progress on trial/3 (merged as ff7a251): the server, CLI and transformer parts are now done, in addition to the earlier lib part. The SQL and UI-framework parts follow in a short final pass. Leaving open.

Now complete across all crates on trial/3 (final pass 28b3826, merged as 7031282; earlier parts in 644795f and 407b4d6). Not yet on main, so leaving open.

Accurate # Errors sections added for public fallible SQL and framework APIs.
Coordinator-verified on the combined code: fmt, Clippy -D warnings, Rustdoc -D warnings, cargo +1.96.0 check, 470 workspace tests and 867 doctests pass; the profile UI check passes for both in-memory and SQLite backends, with all 16 browser proofs.

Fix owner review issues #11, #1, #2, #5 and lib parts of #4, #7 (task…

Fix owner review issues #10, #3, #8, #9, #13, #12 and host parts of #4,

Finish owner review issues #4, #6, #7 for SQL and framework; neutral …

Navigation Menu

Repository navigation

Documentation volume does not consistently cover failure contracts #7

Problem

Evidence

Acceptance criteria

Code examples and suggested direction

Suggested investigation and fix notes

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Documentation volume does not consistently cover failure contracts #7

Description

Problem

Evidence

Acceptance criteria

Code examples and suggested direction

Activity

cblanquera commented on Oct 26, 2026

Suggested investigation and fix notes

cblanquera commented on Oct 26, 2026

cblanquera commented on Oct 26, 2026

cblanquera commented on Oct 26, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions