[docs] Make doc builds cleaner and require this in CI

[Mark Hildebrand (hildebrandmw)]

Our docs (such as they are) have suffered from various issues preventing a clean, warning free doc build. This PR moves this along by getting at least one feature set building cleanly across the workspace and adding clean docs as a blocking CI check.

This PR is best viewed commit by commit as I tried to go one crate at the time (though pivoted in the middle to transition from jut no broken links to a full rustdoc::all).

Fixes fell into several categories:

• Simple formatting errors with backticks or URL tags.
• Incorrect, outdated, or incompletely qualified cross references.
• Missing top-level docs (I added barebones summaries. If you are unhappy with the one applied to your crate, please update it)
• Cross-references to private items (diskann-providers did this a lot)
• Doc examples on private items (the large migration in diskann-quantization/src/minmax/mod.rs was because of this).
• Broken links due to incomplete export lists where items were publicly visible but unnamable due to being in a private module.

I tried to keep the changes as minimal as I could. Let's not litigate over the contents of the docs much in this PR outside of changes made that are clearly wrong - that can happen in follow-ups. Happy, though, to discuss the reexports made here.

There is more follow-up work to do, including auditing the features for each crate used to build the public documentation, teaching CI about those features, and actually making the docs actually good. But we have to start somewhere.

AI disclosure: I am still limited to typing with one hand. A closely monitored agent did the changes and was not left to its own devices for the changes related to visibility.

[Codecov Comments Bot (codecov-commenter)]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.54%. Comparing base (3218478) to head (90a1693).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1334      +/-   ##
==========================================
+ Coverage   91.55%   92.54%   +0.98%     
==========================================
  Files         522      522              
  Lines       99541    99541              
==========================================
+ Hits        91139    92121     +982     
+ Misses       8402     7420     -982     

Flag	Coverage Δ
miri	92.54% <ø> (+0.98%)	⬆️
unittests	92.51% <ø> (+1.27%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
diskann-benchmark-core/src/lib.rs	57.14% <ø> (ø)
diskann-benchmark-core/src/search/graph/mod.rs	100.00% <ø> (ø)
diskann-benchmark-core/src/search/graph/range.rs	95.33% <ø> (ø)
diskann-benchmark-runner/src/files.rs	96.15% <ø> (ø)
diskann-benchmark-simd/src/bin.rs	87.50% <ø> (ø)
diskann-benchmark/src/flat/search.rs	95.75% <ø> (ø)
diskann-benchmark/src/index/streaming/managed.rs	97.53% <ø> (ø)
diskann-benchmark/src/index/streaming/stats.rs	97.70% <ø> (ø)
diskann-benchmark/src/inputs/graph_index.rs	58.98% <ø> (ø)
diskann-benchmark/src/main.rs	92.21% <ø> (ø)
... and 59 more

... and 43 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Mark Hildebrand (hildebrandmw)]

Note: this example is copied verbatim by the public PerfLogger. We aren't losing it.

[Mark Hildebrand (hildebrandmw)]

This is a victim of "example on private docs" since multi_vector is private. I moved it up one level to the module level docs for minmax.

[Copilot]

Pull request overview

This PR focuses on making Rustdoc builds warning-free (or closer to it) across the DiskANN workspace by fixing broken/invalid intra-doc links, tightening/clarifying doc text, adding minimal crate-level docs where missing, and re-enabling docs as a required CI job.

Changes:

• Fix many Rustdoc issues across crates (broken intra-doc links, malformed markdown/backticks/URLs, and references to private/unnameable items).
• Add minimal crate/module-level documentation headers to reduce rustdoc lint noise.
• Re-enable and require a docs job in CI to enforce clean doc builds.

Reviewed changes

Copilot reviewed 85 out of 85 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
diskann/src/utils/vector_repr.rs	Doc wording cleanup for VectorRepr and link typo fix
diskann/src/provider.rs	Doc grammar fix for ExecutionContext
diskann/src/neighbor/mod.rs	Update doc guidance on sorting neighbors (intra-doc link change)
diskann/src/lib.rs	Add crate-level docs header
diskann/src/graph/workingset/mod.rs	Fix intra-doc links to correct accessor traits
diskann/src/graph/search/mod.rs	Export additional search builder type and adjust docs
diskann/src/graph/index.rs	Fix intra-doc links and improve references to Config/search types
diskann/src/graph/glue.rs	Fix intra-doc links and naming for graph “glue” docs
diskann/src/graph/ext/labeled.rs	Fix intra-doc link formatting
diskann/src/graph/config/mod.rs	Fix doc link typo and simplify builder docs
diskann/src/graph/adjacencylist.rs	Update docs for last() and sorting link
diskann/src/flat/mod.rs	Fix doc link to the correct accessor family
diskann/src/flat/index.rs	Fix doc link formatting for DataProvider
diskann/src/error/ranked.rs	Fix macro link paths in docs
diskann-wide/src/traits.rs	Fix intra-doc links for SplitJoin methods
diskann-utils/src/object_pool.rs	Fix doc links to renamed methods and correct type name
diskann-utils/src/lib.rs	Add crate-level docs header
diskann-tools/src/lib.rs	Add crate-level docs header
diskann-tools/src/bin/subsample_bin.rs	Add binary-level docs header
diskann-tools/src/bin/relative_contrast.rs	Fix URL/docs formatting and add reference link
diskann-tools/src/bin/random_data_generator.rs	Add binary-level docs header
diskann-tools/src/bin/generate_synthetic_labels.rs	Add binary-level docs header
diskann-tools/src/bin/generate_pq.rs	Add binary-level docs header
diskann-tools/src/bin/generate_minmax.rs	Add binary-level docs header
diskann-tools/src/bin/gen_associated_data_from_range.rs	Add binary-level docs header
diskann-tools/src/bin/compute_streaming_groundtruth.rs	Fix doc formatting for output filename pattern
diskann-tools/src/bin/compute_specificities.rs	Add binary-level docs header
diskann-tools/src/bin/compute_range_groundtruth.rs	Add binary-level docs header
diskann-tools/src/bin/compute_multivec_groundtruth.rs	Add binary-level docs header
diskann-tools/src/bin/compute_groundtruth.rs	Add binary-level docs header
diskann-quantization/src/multi_vector/mod.rs	Re-export additional matrix API type
diskann-quantization/src/multi_vector/matrix.rs	Clarify Repr layout docs
diskann-quantization/src/minmax/multi/mod.rs	Remove large private-item-heavy example from submodule docs
diskann-quantization/src/minmax/multi/meta.rs	Fix doc link for stride computation
diskann-quantization/src/minmax/mod.rs	Add multi-vector support docs + example at the public module level
diskann-quantization/src/meta/vector.rs	Fix backtick formatting in error docs
diskann-quantization/src/meta/slice.rs	Fix markdown/backtick formatting and doc typos
diskann-quantization/src/bits/slice.rs	Fix missing closing backtick
diskann-quantization/src/bits/distances.rs	Fix doc references and markdown formatting
diskann-providers/src/utils/vector_data_iterator.rs	Wrap long format docs and fix backticks
diskann-providers/src/storage/pq_storage.rs	Update docs to reference correct API for legacy centering
diskann-providers/src/model/pq/distance/dynamic.rs	Fix backtick formatting (Metric)
diskann-providers/src/model/graph/provider/layers/mod.rs	Update docs and change betafilter module visibility
diskann-providers/src/model/graph/provider/layers/betafilter.rs	Fix docs to match glue::SearchAccessor terminology and links
diskann-providers/src/model/graph/provider/async_/simple_neighbor_provider.rs	Remove broken “See also” doc links
diskann-providers/src/model/graph/provider/async_/memory_vector_provider.rs	Doc typo fixes and remove broken “See also” links
diskann-providers/src/model/graph/provider/async_/memory_quant_vector_provider.rs	Doc typo fixes and simplify “See also” references
diskann-providers/src/model/graph/provider/async_/inmem/spherical.rs	Doc clarification and link formatting changes
diskann-providers/src/model/graph/provider/async_/inmem/scalar.rs	Update docs to correct trait/type names and formatting
diskann-providers/src/model/graph/provider/async_/inmem/provider.rs	Fix doc links to the correct strategy/store types
diskann-providers/src/model/graph/provider/async_/inmem/full_precision.rs	Update docs to reflect glue::SearchAccessor and post-process trait name
diskann-providers/src/model/graph/provider/async_/fast_memory_vector_provider.rs	Doc typo fixes and remove broken “See also” links
diskann-providers/src/model/graph/provider/async_/fast_memory_quant_vector_provider.rs	Doc typo fixes and simplify “See also” references
diskann-providers/src/lib.rs	Add crate-level docs header and deprecation note
diskann-providers/src/index/wrapped_async.rs	Simplify intra-doc link paths for LoadWith
diskann-providers/src/common/mod.rs	Re-export additional error type to support doc naming/linking
diskann-providers/src/common/minmax_repr.rs	Update error docs and fix type reference
diskann-linalg/src/lib.rs	Add crate-level docs + fix code block language and URL formatting
diskann-label-filter/src/traits/attribute_accessor.rs	Remove incorrect trait bounds from docs
diskann-label-filter/src/stores/bftree_store.rs	Improve thread-safety doc formatting
diskann-label-filter/src/parser/ast.rs	Fix URL formatting
diskann-label-filter/src/lib.rs	Add crate-level docs header
diskann-label-filter/src/inline_beta_search/predicate_evaluator.rs	Fix markdown formatting for generic types
diskann-label-filter/src/inline_beta_search/inline_beta_filter.rs	Clarify DefaultPostProcessor delegation docs
diskann-label-filter/src/encoded_attribute_provider/encoded_attribute_accessor.rs	Fix markdown formatting for Set<u64>
diskann-garnet/src/lib.rs	Add crate-level docs header
diskann-disk/src/utils/instrumentation/perf_logger.rs	Remove private-item doc example likely failing rustdoc lints
diskann-disk/src/storage/quant/compressor.rs	Doc cleanup and fully qualify referenced types
diskann-disk/src/search/provider/disk_provider.rs	Remove broken RFC link reference
diskann-disk/src/error.rs	Fix “macro” typo and avoid linking internal macro as public
diskann-bftree/src/provider.rs	Update docs to use correct SearchAccessor naming/paths
diskann-bftree/src/id.rs	Fix doc link formatting around validate_id_capacity
diskann-benchmark/src/main.rs	Add crate-level docs header
diskann-benchmark/src/inputs/graph_index.rs	Fix intra-doc link to IntraBatchCandidates
diskann-benchmark/src/index/streaming/stats.rs	Fix Display link qualification
diskann-benchmark/src/index/streaming/managed.rs	Fix module name typo in doc link and qualify type paths
diskann-benchmark/src/flat/search.rs	Simplify intra-doc link reference for Search
diskann-benchmark-simd/src/bin.rs	Add crate-level docs header
diskann-benchmark-runner/src/files.rs	Fix doc typo/backticks
diskann-benchmark-core/src/streaming/executors/mod.rs	Fix intra-doc link path qualification
diskann-benchmark-core/src/search/mod.rs	Update public re-exports and fix docs for graph search helpers
diskann-benchmark-core/src/search/graph/range.rs	Adjust docs to match current range-search API surface
diskann-benchmark-core/src/search/graph/mod.rs	Re-export FilteredRange publicly
diskann-benchmark-core/src/lib.rs	Fix module naming in docs (executors vs runbooks)
.github/workflows/ci.yml	Re-enable docs job as a required CI check and enforce rustdoc lints

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.