chore(publish-prep): opt the 5 publishable lib crates into docs.rs cfg-badge rendering#242
Merged
Merged
Conversation
…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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
#![cfg_attr(docsrs, feature(doc_cfg))]to thelib.rsof every publishable library crate so that docs.rs renders cfg-availability badges on cfg-gated public items.The 5 lib crates touched:
#![…]neighboursuffs-timecrates/uffs-time/src/lib.rs#![no_std]uffs-textcrates/uffs-text/src/lib.rs#![…])uffs-mftcrates/uffs-mft/src/lib.rs#![warn(…)]clusteruffs-clientcrates/uffs-client/src/lib.rsuffs-mcpcrates/uffs-mcp/src/lib.rsuffs-cliis binary-only (nolib.rs) — no directive needed.Why
Each publishable crate already declares the docs.rs rendering hint in its manifest:
--cfg docsrsonly 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 docdoes not pass--cfg docsrs, so thecfg_attrwrapper bypasses the directive entirely — the nightly-onlydoc_cfgfeature is never exercised in normal workflows.Why
doc_cfg, notdoc_auto_cfgThe earlier-typed
doc_auto_cfggot rejected by rustc:Rust 1.92 (rust-lang/rust#138907) merged
doc_auto_cfgintodoc_cfg. The unifieddoc_cfgfeature provides both the explicit#[doc(cfg(…))]attribute and the automatic cfg-badge inference behaviour thatdoc_auto_cfgused to offer alone. Our pinned nightly (nightly-2026-05-14perrust-toolchain.toml, rustc 1.97-nightly) is well past the merge.Verification
Locally on macOS Apple Silicon, all of these pass:
The pre-push
lint-pre-pushgate (smoke + lint-ci-windows) also passed before push.Adherence to the 5 user-mandated rules
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.#![cfg_attr(…)]line plus a justifying comment block.--cfg docsrs) bypass the directive entirely; only docs.rs rendering is affected.doc_auto_cfg→doc_cfgmigration.Scope context
Part of the crates.io publish-readiness umbrella tracked in #241, specifically gap #2 (the
doc_auto_cfgdirective item). One more PR-B remains in that umbrella (per-cratekeywords+categoriesallow-list + apply) before the actionable-now backlog is closed.Test plan
cargo checkon the 2 polars-free cratesRUSTDOCFLAGS="--cfg docsrs" cargo doc --no-depson all 5 lib cratescargo fmt --checkcargo clippy -- -D warningson the 2 polars-free crateslint-pre-push(smoke + lint-ci-windows) passes pre-pushRefs: #241