ci(lint): gate rustdoc warnings in lint-rust (paradedb#5562)

## What

Add a Rustdoc step to `lint-rust` (`RUSTDOCFLAGS="-D warnings" cargo doc
--workspace --no-deps --document-private-items`) so broken intra-doc
links, bare URLs, and malformed HTML in doc comments fail CI, and clear
the 53 pre-existing warnings that surface under
`--document-private-items`.

Follow-up to the doc-link fix in paradedb#5547, which noted the linter would
have caught it — this wires up that gate.

## The fixes

- **De-link** intra-doc references that don't resolve (out-of-scope,
private, or local-variable targets), keeping the backticked inline code
— e.g. `[`ExecMethod`]` → ``ExecMethod``.
- **Path typos**: `pg_sys:Buffer` → `pg_sys::Buffer`.
- **Bare URLs** wrapped in angle brackets.
- **Generic type expressions** (`Option<i16>`, `Vec<Datum>`,
`<uuid>.<ext>`) backticked so rustdoc stops parsing them as unclosed
HTML tags.

No runtime code changed — doc comments only, plus the workflow step.

## Notes

- `--document-private-items` is what catches most of these:
crate-internal modules (`mod foo;`) are skipped by default `cargo doc`.
- Matches Clippy's default feature set (single pg version), so cfg-gated
doc links aren't covered — a link that only breaks under a disabled
`#[cfg]` won't be caught. Acceptable for now.
- The `proc-macro-error2` future-incompat notice is a dependency-level
cargo report, not a rustdoc lint, so it doesn't trip `-D warnings`.

## Tests

- `RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps
--document-private-items` — clean (exit 0).
- Same with the default (public-only) doc build — clean.
- `cargo fmt -- --check` — clean.

https://claude.ai/code/session_01369qmSBKYCAXRv1qJsKS8g

---------

Signed-off-by: Philippe Noël <21990816+philippemnoel@users.noreply.github.com>

Author: philippemnoel

.github/workflows/lint-rust.yml

@@ -81,6 +81,11 @@ jobs:
       - name: Run Rustfmt
         run: cargo fmt -- --check
 
+      - name: Run Rustdoc
+        env:
+          RUSTDOCFLAGS: "-D warnings"
+        run: cargo doc --workspace --no-deps --document-private-items
+
       - name: Run Clippy
         run: cargo clippy --workspace --all-targets -- -D warnings --no-deps
 

benchmarks/src/lib.rs

@@ -62,7 +62,7 @@ pub fn mean(data: &[f64]) -> f64 {
 /// Returns the half-width of the confidence interval for the provided confidence level
 ///
 /// The math for this comes from single-level version of what is shown in this paper:
-/// https://dl.acm.org/doi/10.1145/2555670.2464160.
+/// <https://dl.acm.org/doi/10.1145/2555670.2464160>.
 pub fn confidence_interval_half_width(data: &[f64], confidence_level: f64) -> f64 {
     assert!(!data.is_empty());
     assert!(confidence_level > 0.0);

pg_search/src/index/directory/mvcc.rs

@@ -57,7 +57,7 @@ use tantivy::{Directory, IndexMeta, SegmentMeta, TantivyError};
 /// which creates less lock contention than allocating one block at a time.
 pub const BUFWRITER_CAPACITY: usize = bm25_max_free_space() * MAX_BUFFERS_TO_EXTEND_BY;
 
-/// Describes how a [`MvccDirectory`] should resolve segment visibility.  Note that
+/// Describes how a `MvccDirectory` should resolve segment visibility.  Note that
 /// this enum is purposely non-cloneable.  Wrap it with an [`Arc`] if you need that.  Because of
 /// the [`MvccSatisfies::ParallelWorker`] variant, cloning could be incredibly expensive when
 /// an index has many (thousands!) of segments.
@@ -389,7 +389,7 @@ impl Directory for MVCCDirectory {
     }
 
     /// Returns a list of all segment components to Tantivy,
-    /// identified by <uuid>.<ext> PathBufs
+    /// identified by `<uuid>.<ext>` PathBufs
     fn list_managed_files(&self) -> tantivy::Result<std::collections::HashSet<PathBuf>> {
         unsafe {
             Ok(MetaPage::open(&self.indexrel)

pg_search/src/postgres/catalog.rs

@@ -235,7 +235,7 @@ pub fn lookup_database_collation_locale() -> Option<CollationLocale> {
 }
 
 /// Helper function to lookup the `collcollate` and `collprovider` fields for a collation object in `pg_collation`
-/// Note that while `collprovider` is always present in `pg_collation`, `collcollate` may be NULL: https://www.postgresql.org/docs/current/catalog-pg-collation.html
+/// Note that while `collprovider` is always present in `pg_collation`, `collcollate` may be NULL: <https://www.postgresql.org/docs/current/catalog-pg-collation.html>
 pub fn lookup_collation_locale(collation: pg_sys::Oid) -> Option<CollationLocale> {
     unsafe {
         let entry =

pg_search/src/postgres/composite.rs

@@ -227,7 +227,7 @@ pub unsafe fn get_composite_fields_for_index(
 /// ```sql
 /// CREATE INDEX idx ON t USING bm25 (id, ROW(a,b,c)::my_type);
 /// ```
-/// The composite at values[1] is unpacked once during construction.
+/// The composite at `values[1]` is unpacked once during construction.
 /// Fields "a", "b", "c" are then retrieved via simple lookups.
 ///
 /// # Lifetime

pg_search/src/postgres/customscan/aggregatescan/aggregate_type.rs

@@ -404,7 +404,7 @@ impl AggregateType {
     /// - Any referenced field is a NUMERIC type (not supported for aggregation)
     ///
     /// TODO: remove field existence check once Tantivy aggregation validation is fixed.
-    /// https://github.com/quickwit-oss/tantivy/issues/2767
+    /// <https://github.com/quickwit-oss/tantivy/issues/2767>
     pub fn validate_fields(&self, schema: &SearchIndexSchema) -> Result<(), String> {
         // Check NUMERIC field support for standard aggregates
         if let Some(field) = self.field_name() {

pg_search/src/postgres/customscan/aggregatescan/datafusion_build.rs

@@ -174,7 +174,7 @@ pub unsafe fn collect_join_agg_sources(
 ///    the planner has absorbed WHERE-clause quals into `RestrictInfo` lists on
 ///    the planned `JoinPath` nodes - so `(*from).quals` can be null even for
 ///    `SELECT ... FROM a, b WHERE a.id = b.id`. We recursively walk the path
-///    tree via [`extract_equi_keys_from_path`], inspecting each `JoinPath`'s
+///    tree via `extract_equi_keys_from_path`, inspecting each `JoinPath`'s
 ///    `joinrestrictinfo` for `OpExpr` nodes with merge-joinable (equality)
 ///    operators whose two sides reference different base relations.
 ///
@@ -1287,8 +1287,8 @@ unsafe fn all_vars_are_fast_fields_for_agg(
 }
 
 /// Transform collected cross-table clause pointers into a `JoinLevelExpr`
-/// tree by delegating to JoinScan's [`transform_to_search_expr`] via a
-/// temporary [`JoinCSClause`]. After plan_positions have been assigned,
+/// tree by delegating to JoinScan's `transform_to_search_expr` via a
+/// temporary `JoinCSClause`. After plan_positions have been assigned,
 /// `plan.sources()` returns `&[&JoinSource]` - the same type JoinScan uses -
 /// so the shared function works directly.
 ///

pg_search/src/postgres/customscan/aggregatescan/join_targetlist.rs

@@ -55,7 +55,7 @@ fn find_source_by_rti<'a>(
 }
 
 /// Simplified aggregate classification for the DataFusion backend.
-/// Unlike [`AggregateType`] (Tantivy-oriented), this enum is lightweight and maps
+/// Unlike `AggregateType` (Tantivy-oriented), this enum is lightweight and maps
 /// directly to DataFusion aggregate expressions.
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
 pub enum AggKind {

pg_search/src/postgres/customscan/aggregatescan/mod.rs

@@ -1916,7 +1916,7 @@ unsafe fn group_key_to_datum(
 }
 
 /// Detects ORDER BY + LIMIT for join aggregate queries and returns a
-/// [`DataFusionTopK`] describing the sort target, direction, and K.
+/// `DataFusionTopK` describing the sort target, direction, and K.
 ///
 /// Supports two patterns:
 /// - **ORDER BY aggregate LIMIT K** (e.g., `ORDER BY COUNT(*) DESC LIMIT 5`)

pg_search/src/postgres/customscan/aggregatescan/scan_state.rs

@@ -75,7 +75,7 @@ pub struct DataFusionAggState {
     pub current_batch: Option<RecordBatch>,
     /// Row index within current_batch.
     pub batch_row_idx: usize,
-    /// Mapping from group_columns[i] to its 0-based column index in DataFusion's
+    /// Mapping from `group_columns[i]` to its 0-based column index in DataFusion's
     /// output RecordBatch. Needed because DataFusion deduplicates grouping
     /// expressions (e.g. metadata.brand).
     pub group_df_indices: Vec<usize>,