Skip to content

Resolve ~420 missing-docs warnings across public API #34

Description

@coreyt

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:

  1. 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.
  2. 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.
  3. 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:

  1. Add //! crate-level docs to each lib.rs.
  2. Document the top-level public API surface in fathomdb-engine (the re-exports in lib.rs) — these are what external consumers see first.
  3. Document public DTOs field-by-field. For serde-shaped structs, field docs should describe the wire meaning, not just the Rust type.
  4. 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)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions