Summary
The workspace sets missing_docs = "warn" in the root Cargo.toml:21, and a full build currently emits ~420 missing documentation warnings across the public API. They are non-blocking (warnings, not errors) but noisy enough to drown out real diagnostics and leave docs.rs coverage spotty for a published crate.
Warning counts per crate
Captured from cargo build --all-targets --features sqlite-vec,tracing:
| Crate |
Warnings |
fathomdb-engine (lib) |
371 |
fathomdb-schema (lib) |
21 |
fathomdb-query (lib) |
17 |
fathomdb (lib) |
10 |
fathomdb (build script) |
1 |
| Total |
~420 |
Each warning falls into one of three categories:
- Missing crate-level docs — e.g.
crates/fathomdb-engine/src/lib.rs, crates/fathomdb/src/lib.rs, crates/fathomdb-query/src/lib.rs. Every public crate should have a //! module doc at the top describing its purpose.
- Missing docs on public structs / enums / functions — the bulk of the 371 warnings in
fathomdb-engine are public items re-exported from lib.rs with no /// doc comment.
- Missing docs on public struct fields — many
#[derive(Serialize, Deserialize)] DTOs (e.g. crates/fathomdb/src/feedback.rs:29-37, crates/fathomdb-engine/src/writer.rs:221-236) expose pub fields without per-field documentation.
Why this matters
- docs.rs quality:
fathomdb is published to npm and will eventually need rustdoc coverage for Rust consumers. Right now anything on docs.rs for these crates would render as a sea of undocumented symbols.
- Signal-to-noise: 420 warnings per build makes it hard to spot new warnings introduced by a change. Real issues hide in the noise.
- Upgrading to
deny: Once the backlog is cleared, missing_docs = "deny" would prevent regressions, but that is infeasible today.
Suggested approach
Rather than one mega-PR, split by crate and by item kind:
- Add
//! crate-level docs to each lib.rs.
- Document the top-level public API surface in
fathomdb-engine (the re-exports in lib.rs) — these are what external consumers see first.
- Document public DTOs field-by-field. For serde-shaped structs, field docs should describe the wire meaning, not just the Rust type.
- Once a crate hits zero warnings, bump its lint to
missing_docs = "deny" at the crate level to lock in progress.
Non-goals
- Not trying to document private/internal items.
- Not trying to write end-user tutorials — just rustdoc coverage sufficient to silence the lint meaningfully.
Reproduction
cargo build --all-targets --features sqlite-vec,tracing 2>&1 | grep -c "^warning: missing documentation"
# 441 (includes a few duplicates across lib/lib-test)
Summary
The workspace sets
missing_docs = "warn"in the rootCargo.toml:21, and a full build currently emits ~420missing documentationwarnings across the public API. They are non-blocking (warnings, not errors) but noisy enough to drown out real diagnostics and leave docs.rs coverage spotty for a published crate.Warning counts per crate
Captured from
cargo build --all-targets --features sqlite-vec,tracing:fathomdb-engine(lib)fathomdb-schema(lib)fathomdb-query(lib)fathomdb(lib)fathomdb(build script)Each warning falls into one of three categories:
crates/fathomdb-engine/src/lib.rs,crates/fathomdb/src/lib.rs,crates/fathomdb-query/src/lib.rs. Every public crate should have a//!module doc at the top describing its purpose.fathomdb-engineare public items re-exported fromlib.rswith no///doc comment.#[derive(Serialize, Deserialize)]DTOs (e.g.crates/fathomdb/src/feedback.rs:29-37,crates/fathomdb-engine/src/writer.rs:221-236) exposepubfields without per-field documentation.Why this matters
fathomdbis published to npm and will eventually need rustdoc coverage for Rust consumers. Right now anything on docs.rs for these crates would render as a sea of undocumented symbols.deny: Once the backlog is cleared,missing_docs = "deny"would prevent regressions, but that is infeasible today.Suggested approach
Rather than one mega-PR, split by crate and by item kind:
//!crate-level docs to eachlib.rs.fathomdb-engine(the re-exports inlib.rs) — these are what external consumers see first.missing_docs = "deny"at the crate level to lock in progress.Non-goals
Reproduction