Skip to content

chore(publish-prep): opt the 5 publishable lib crates into docs.rs cfg-badge rendering#242

Merged
githubrobbi merged 1 commit into
mainfrom
publish/doc-auto-cfg
May 15, 2026
Merged

chore(publish-prep): opt the 5 publishable lib crates into docs.rs cfg-badge rendering#242
githubrobbi merged 1 commit into
mainfrom
publish/doc-auto-cfg

Conversation

@githubrobbi
Copy link
Copy Markdown
Collaborator

What

Adds #![cfg_attr(docsrs, feature(doc_cfg))] to the lib.rs of every publishable library crate so that docs.rs renders cfg-availability badges on cfg-gated public items.

The 5 lib crates touched:

Crate Insertion site Existing #![…] neighbours
uffs-time crates/uffs-time/src/lib.rs grouped with #![no_std]
uffs-text crates/uffs-text/src/lib.rs standalone (no other #![…])
uffs-mft crates/uffs-mft/src/lib.rs grouped with the existing #![warn(…)] cluster
uffs-client crates/uffs-client/src/lib.rs standalone
uffs-mcp crates/uffs-mcp/src/lib.rs standalone

uffs-cli is binary-only (no lib.rs) — no directive needed.

Why

Each publishable crate already declares the docs.rs rendering hint in its manifest:

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]

--cfg docsrs only takes effect when the crate root opts in. With this attribute, items behind #[cfg(feature = "async")], #[cfg(windows)], #[cfg(target_os = "…")], etc. render with their cfg-availability badge on docs.rs. Without it, those badges silently don't appear.

Local cargo doc does not pass --cfg docsrs, so the cfg_attr wrapper bypasses the directive entirely — the nightly-only doc_cfg feature is never exercised in normal workflows.

Why doc_cfg, not doc_auto_cfg

The earlier-typed doc_auto_cfg got rejected by rustc:

error[E0557]: feature has been removed
  --> crates/uffs-text/src/lib.rs:38:29
   |
38 | #![cfg_attr(docsrs, feature(doc_auto_cfg))]
   |                             ^^^^^^^^^^^^ feature has been removed
   |
   = note: removed in 1.92.0; see <https://github.com/rust-lang/rust/pull/138907> for more information
   = note: merged into `doc_cfg`

Rust 1.92 (rust-lang/rust#138907) merged doc_auto_cfg into doc_cfg. The unified doc_cfg feature provides both the explicit #[doc(cfg(…))] attribute and the automatic cfg-badge inference behaviour that doc_auto_cfg used to offer alone. Our pinned nightly (nightly-2026-05-14 per rust-toolchain.toml, rustc 1.97-nightly) is well past the merge.

Verification

Locally on macOS Apple Silicon, all of these pass:

cargo check -p uffs-time -p uffs-text                        # OK
RUSTDOCFLAGS="--cfg docsrs" cargo doc -p uffs-time -p uffs-text -p uffs-mft -p uffs-client -p uffs-mcp --no-deps   # OK
cargo fmt --check                                            # OK
cargo clippy -p uffs-time -p uffs-text -- -D warnings        # OK

The pre-push lint-pre-push gate (smoke + lint-ci-windows) also passed before push.

Adherence to the 5 user-mandated rules

  1. No suppression hacks — the directive is gated behind cfg(docsrs) which is the canonical docs.rs feature-opt-in pattern (used by tokio, serde, tracing, …); it does not suppress any lint, warning, or test.
  2. Surgical fix — 36 lines added across 5 files, each a single #![cfg_attr(…)] line plus a justifying comment block.
  3. Preserve behaviour — no public API changes. Local builds (no --cfg docsrs) bypass the directive entirely; only docs.rs rendering is affected.
  4. Tests — no existing tests touched; no new tests added because the directive has zero runtime / type-system surface (it's a rustdoc-only opt-in).
  5. Documented & atomic — single commit, conventional-commit subject, detailed body explaining the why and the doc_auto_cfgdoc_cfg migration.

Scope context

Part of the crates.io publish-readiness umbrella tracked in #241, specifically gap #2 (the doc_auto_cfg directive item). One more PR-B remains in that umbrella (per-crate keywords + categories allow-list + apply) before the actionable-now backlog is closed.

Test plan

  • cargo check on the 2 polars-free crates
  • RUSTDOCFLAGS="--cfg docsrs" cargo doc --no-deps on all 5 lib crates
  • cargo fmt --check
  • cargo clippy -- -D warnings on the 2 polars-free crates
  • lint-pre-push (smoke + lint-ci-windows) passes pre-push

Refs: #241

…g-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
@githubrobbi githubrobbi enabled auto-merge (squash) May 15, 2026 10:31
@githubrobbi githubrobbi merged commit 060a231 into main May 15, 2026
20 checks passed
@githubrobbi githubrobbi deleted the publish/doc-auto-cfg branch May 15, 2026 10:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant