docs.rs shows the gated modules but not which feature each item needs
- Ngôn ngữ chính
- Rust
- Star
- 9
- Fork
- 1
- Merge trung bình
- 11 giờ 46 phút
- Pull request đã merge (30 ngày)
- 62
Mô tả
## What
Since #384 the `subscription::http` and `subscription::websocket` pages exist on docs.rs, and since #394 the list that puts them there is held by `just test-doc-packaged` and rendered locally by `just doc-declared`. What those pages do not carry is any statement of which feature an item needs: `Query`, `Mutation`, `WebSocket` and `WebSocketCommand` sit beside items that need no feature at all, with nothing on the page distinguishing them.
The tree does label features where the list is short and hand-kept. `src/subscription.rs` writes its built-in list with one `#![cfg_attr(feature = "ws", doc = "…")]` per line. That covers a module's own list, not the item pages a reader lands on from search.
## Why it is not a one-liner
Two constraints, both recorded rather than guessed.
**The check that holds the manifest table refuses `rustdoc-args`.** `test-doc-packaged`'s third arm rejects every key in `[package.metadata.docs.rs]` but `features`, and states the reason: `doc-declared` renders from `features` alone, so a key it does not pass would leave the check and the render disagreeing in silence. Enabling labels through the manifest means teaching the check and the recipe in the same change.
**The labelled render is not reachable from the pinned toolchain.** Measured on a probe crate under 1.97.0 rather than assumed:
- `#![cfg_attr(docsrs, feature(doc_auto_cfg))]` rendered with `RUSTDOCFLAGS='--cfg docsrs'` fails: `error[E0554]: #![feature] may not be used on the stable release channel`.
- Without `--cfg docsrs` it builds, and the page for a `#[cfg(feature = "extra")]` item carries no "Available on" label.
So `doc-declared` under the pinned toolchain renders the same feature set as docs.rs and a different page. That is the part a design has to answer: the local render becomes either a narrowing that no longer matches what publishes, or a second render under a toolchain this repository does not pin.
## Options, none of them settled
- **`doc_auto_cfg` behind `--cfg docsrs`.** Labels every gated item with no per-item edit. Costs the manifest key the check refuses today, and leaves the local render unlabelled for the reason measured above.
- **Per-item `#[cfg_attr(feature = "…", doc = "…")]`.** No nightly, no manifest key, and `doc-declared` renders exactly what publishes. Costs a hand-kept line per item, which is the shape `subscription.rs` already carries for a list of six and would now carry for every gated public item.
- **Accept it,** on the ground that a reader arriving at `subscription::http` reaches it through a module whose docs say the feature, and record that where the check is rather than leaving it implied.
## Acceptance criteria
- [ ] A reader on docs.rs can tell from an item's own page which feature it needs, or the decision not to say so is recorded where a contributor will meet it.
- [ ] Whatever renders the labels is what the manifest check holds — or the two disagreeing is stated at the check rather than discovered after a publish.
## Provenance
Split from #351. Both halves of that issue landed: the modules were absent because docs.rs built the default set (#384), and the list that fixed it had no guard (#394). This is what it left open, and its title had stopped describing it.
Hướng dẫn đóng góp
Đánh giá
Issue này chưa được đánh giá.