From 69db9d9513a0c38ee2cc80864d18c422a855d65b Mon Sep 17 00:00:00 2001
From: Robert M1 <50460704+githubrobbi@users.noreply.github.com>
Date: Fri, 15 May 2026 03:27:14 -0700
Subject: [PATCH] chore(publish-prep): opt the 5 publishable lib crates into
 docs.rs cfg-badge rendering

Adds `#![cfg_attr(docsrs, feature(doc_cfg))]` to the lib.rs entry points
of the five publishable library crates (`uffs-time`, `uffs-text`,
`uffs-mft`, `uffs-client`, `uffs-mcp`).  `uffs-cli` is binary-only and
needs no directive.

When docs.rs renders these crates it passes `--cfg docsrs` (configured
in each crate's existing `[package.metadata.docs.rs]` block).  With
this attribute, cfg-gated items (`#[cfg(feature = "async")]`,
`#[cfg(windows)]`, `#[cfg(target_os = "...")]`, etc.) automatically
render with their availability badge on the generated docs.

Local `cargo doc` (no `--cfg docsrs`) bypasses the directive entirely
via the `cfg_attr` wrapper, so the nightly-only `doc_cfg` feature is
never exercised in normal workflows.

Note: `doc_auto_cfg` was the historical feature name; it was merged
into `doc_cfg` in Rust 1.92 (rust-lang/rust#138907).  The `doc_cfg`
feature now provides both the explicit `#[doc(cfg(...))]` attribute
and the automatic cfg-badge inference.  Our pinned nightly
(`nightly-2026-05-14` per `rust-toolchain.toml`) is rustc 1.97-nightly,
well past the merge.

Verified locally:
- `cargo check -p uffs-time -p uffs-text`
- `RUSTDOCFLAGS="--cfg docsrs" cargo doc -p uffs-time -p uffs-text -p uffs-mft -p uffs-client -p uffs-mcp --no-deps`
- `cargo fmt --check` clean
- `cargo clippy -p uffs-time -p uffs-text -- -D warnings` clean

Part of the crates.io publish-readiness umbrella (issue #241), gap #2.

Refs: #241
---
 crates/uffs-client/src/lib.rs | 7 +++++++
 crates/uffs-mcp/src/lib.rs    | 7 +++++++
 crates/uffs-mft/src/lib.rs    | 6 ++++++
 crates/uffs-text/src/lib.rs   | 7 +++++++
 crates/uffs-time/src/lib.rs   | 9 +++++++++
 5 files changed, 36 insertions(+)

diff --git a/crates/uffs-client/src/lib.rs b/crates/uffs-client/src/lib.rs
index 0fa9479ef..8e4a8f748 100644
--- a/crates/uffs-client/src/lib.rs
+++ b/crates/uffs-client/src/lib.rs
@@ -34,6 +34,13 @@
 //!   `uffs-cli`.
 //! - **§3.7** N/A — no `pub trait` declarations in this crate.
 
+// On docs.rs only: enable the `doc_cfg` rustdoc feature so cfg-gated items
+// (`#[cfg(feature = "async")]`, `#[cfg(windows)]`, etc.) render with their
+// cfg badge.  Gated behind `cfg(docsrs)` so local `cargo doc` never
+// exercises the nightly-only feature.  Post-Rust-1.92 the `doc_auto_cfg`
+// feature was merged into `doc_cfg` (rust-lang/rust#138907).
+#![cfg_attr(docsrs, feature(doc_cfg))]
+
 // Suppress unused crate warnings for deps used in sub-modules
 use serde as _;
 use uffs_security as _;
diff --git a/crates/uffs-mcp/src/lib.rs b/crates/uffs-mcp/src/lib.rs
index a3ae82000..1c4fffe34 100644
--- a/crates/uffs-mcp/src/lib.rs
+++ b/crates/uffs-mcp/src/lib.rs
@@ -26,6 +26,13 @@
 //! # }
 //! ```
 
+// On docs.rs only: enable the `doc_cfg` rustdoc feature so cfg-gated items
+// render with their cfg badge.  Gated behind `cfg(docsrs)` so local
+// `cargo doc` never exercises the nightly-only feature.  Post-Rust-1.92
+// the `doc_auto_cfg` feature was merged into `doc_cfg`
+// (rust-lang/rust#138907).
+#![cfg_attr(docsrs, feature(doc_cfg))]
+
 // `clap` is used by the `uffsmcp` binary, not this library crate.
 use clap as _;
 
diff --git a/crates/uffs-mft/src/lib.rs b/crates/uffs-mft/src/lib.rs
index 54682d970..11282897c 100644
--- a/crates/uffs-mft/src/lib.rs
+++ b/crates/uffs-mft/src/lib.rs
@@ -90,6 +90,12 @@
 //! No `pub trait` declarations live in this crate, so the
 //! sealed-trait decision (§3.7) is **N/A**.
 
+// On docs.rs only: enable the `doc_cfg` rustdoc feature so cfg-gated items
+// (`#[cfg(windows)]`, `#[cfg(feature = "...")]`, etc.) render with their
+// cfg badge.  Gated behind `cfg(docsrs)` so local `cargo doc` never
+// exercises the nightly-only feature.  Post-Rust-1.92 the `doc_auto_cfg`
+// feature was merged into `doc_cfg` (rust-lang/rust#138907).
+#![cfg_attr(docsrs, feature(doc_cfg))]
 #![warn(clippy::all, clippy::pedantic)]
 #![expect(
     clippy::module_name_repetitions,
diff --git a/crates/uffs-text/src/lib.rs b/crates/uffs-text/src/lib.rs
index 625aa2040..92140a132 100644
--- a/crates/uffs-text/src/lib.rs
+++ b/crates/uffs-text/src/lib.rs
@@ -32,4 +32,11 @@
 //! - Locale-aware collation
 //! - Search tokenisation
 
+// On docs.rs only: enable the `doc_cfg` rustdoc feature so cfg-gated items
+// render with their cfg badge.  Gated behind `cfg(docsrs)` so local
+// `cargo doc` never exercises the nightly-only feature.  Post-Rust-1.92
+// the `doc_auto_cfg` feature was merged into `doc_cfg`
+// (rust-lang/rust#138907) — `doc_cfg` is now the unified name.
+#![cfg_attr(docsrs, feature(doc_cfg))]
+
 pub mod case_fold;
diff --git a/crates/uffs-time/src/lib.rs b/crates/uffs-time/src/lib.rs
index c70eed1a8..1c9449d85 100644
--- a/crates/uffs-time/src/lib.rs
+++ b/crates/uffs-time/src/lib.rs
@@ -39,6 +39,15 @@
 //! site.  Future sub-phases may push [`Filetime`] deeper into the index
 //! / query layers.
 
+// On docs.rs only: enable the `doc_cfg` rustdoc feature so cfg-gated items
+// (e.g. `#[cfg(feature = "...")]` or `#[cfg(target_os = "...")]`) render
+// with their cfg badge on the rendered docs.  Gated behind `cfg(docsrs)`
+// so local `cargo doc` (which doesn't pass `--cfg docsrs`) never exercises
+// the nightly-only feature.  See `[package.metadata.docs.rs]` in Cargo.toml
+// for the cfg wiring.  The previously-used `doc_auto_cfg` feature was
+// merged into `doc_cfg` in Rust 1.92 (rust-lang/rust#138907); the unified
+// `doc_cfg` feature preserves the automatic cfg-badge inference behaviour.
+#![cfg_attr(docsrs, feature(doc_cfg))]
 #![no_std]
 
 /// Number of 100-nanosecond intervals per second.