Skip to content

docs: label feature-gated APIs on docs.rs - #267

Merged
vyncint merged 1 commit into
vyncint:mainfrom
nightcityblade:fix/issue-258
Sep 5, 2026
Merged

docs: label feature-gated APIs on docs.rs#267
vyncint merged 1 commit into
vyncint:mainfrom
nightcityblade:fix/issue-258

Conversation

@nightcityblade

Copy link
Copy Markdown
Contributor

What & why

Configure docs.rs to expose feature-gated API badges, and annotate the public decode and insta APIs with their required features.

Closes #258.

Checklist

  • Linked an issue (or explained above why none exists)
  • Tests added/updated for the change (documentation output verified directly)
  • cargo fmt --all and cargo clippy --workspace --all-targets --all-features are clean
  • All commits are signed off (git commit -s) — see CONTRIBUTING.md §5
  • No AI attribution trailers (no AI co-authors, "Generated with" footers, or bot identities) — see CONTRIBUTING.md §6
  • CHANGELOG.md updated under [Unreleased] (user-facing changes only)
  • Snapshot changes (if any) were reviewed with cargo insta review, not blind-accepted (N/A: no snapshots changed)

@vyncint vyncint left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed and verified. This is correct and complete.

What I checked beyond CI:

  • Built the docs on nightly the way docs.rs will (cargo +nightly rustdoc -p termlens --all-features -- --cfg docsrs) and confirmed the badges render: Bitmap, DecodeError and GraphicsPayload::decode show "Available on crate feature decode only", and assert_screen_snapshot! shows the insta one.
  • Confirmed nothing changes on stable: docsrs is never set by a normal build, so feature(doc_cfg) stays inert and clippy with -D warnings is clean in all four feature configurations. Cargo already knows docsrs as a well-known cfg, so there is no unexpected_cfgs warning to suppress.
  • Checked the coverage: decode gates exactly three public declarations plus the re-export, and insta gates the re-export and the macro. You annotated all of them. Bitmap's own methods sit inside a gated impl, so they inherit the type's badge and need nothing.

A nice side effect worth knowing about: enabling doc_cfg also makes rustdoc label the #[cfg(unix)] items automatically, so Signal and Terminal::signal now carry "Available on Unix only" without either of us writing an attribute for them. That is an improvement, not a problem.


One thing to fix, and it is the same in all five of your PRs

The CHANGELOG entry landed inside the published ## [0.9.0] - 2026-09-05 section rather than under ## [Unreleased]. Easy to miss: [Unreleased] was empty when you branched, so the nearest heading with content under it belongs to 0.9.0.

It matters for two reasons. 0.9.0 is already on crates.io and its GitHub Release notes were generated from that section, so the entry now describes a release that does not contain the change. And docs/RELEASING.md cuts the next release by moving [Unreleased] down into a new version heading — an entry parked in [0.9.0] would never appear in any release notes at all.

Move it up under ## [Unreleased], adding the ### Added / ### Changed / ### Fixed sub-heading there if it does not exist yet. main has moved on by a commit since you branched, so a rebase is wanted anyway:

git fetch origin && git rebase origin/main

Thanks for these — five well-scoped fixes with tests and docs, and the PR bodies say what you decided and why. That is exactly the shape this repository asks for.

Signed-off-by: nightcityblade <nightcityblade@gmail.com>
@nightcityblade

Copy link
Copy Markdown
Contributor Author

Rebased onto current main and moved the docs.rs entry under UnreleasedFixed in 8dc0380.

Validation: cargo fmt --check and cargo test --workspace --all-features pass.

@vyncint vyncint left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks — all three points are addressed, and the entry is under [Unreleased] now.

Re-verified on this head: badges render on nightly with --cfg docsrs for Bitmap, DecodeError, GraphicsPayload::decode and assert_screen_snapshot!; stable stays clean in all four feature configurations; docs.rs metadata is right. Merging.

@vyncint
vyncint merged commit 80e3b9b into vyncint:main Sep 5, 2026
13 checks passed
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.

docs.rs shows the decode and insta items with no feature badge, so optional API reads as unconditional

2 participants