user0/rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve code and fix typo

Browse source
This commit is contained in:
Guillaume Gomez 2025-09-25 11:33:58 +02:00
parent 653e1036ed
commit 9362ab549f
7 changed files with 43 additions and 65 deletions
Download patch file Download diff file Expand all files Collapse all files

3
compiler/rustc_passes/messages.ftl
View file

@ -140,9 +140,6 @@ passes_doc_attribute_not_attribute =
nonexistent builtin attribute `{$attribute}` used in `#[doc(attribute = "...")]`
.help = only existing builtin attributes are allowed in core/std
passes_doc_cfg_hide_takes_list =
`#[doc(cfg_hide(...))]` takes a list of attributes
passes_doc_auto_cfg_expects_hide_or_show =
only `hide` or `show` are allowed in `#[doc(auto_cfg(...))]`

41
compiler/rustc_passes/src/check_attr.rs
View file

@ -1160,7 +1160,7 @@ impl<'tcx> CheckAttrVisitor<'tcx> {
}
}
/// Check that the `#![doc(auto_cfg(..))]` attribute has expected input.
/// Check that the `#![doc(auto_cfg)]` attribute has the expected input.
fn check_doc_auto_cfg(&self, meta: &MetaItem, hir_id: HirId) {
match &meta.kind {
MetaItemKind::Word => {}
@ -1176,7 +1176,7 @@ impl<'tcx> CheckAttrVisitor<'tcx> {
}
MetaItemKind::List(list) => {
for item in list {
let Some(attr_name) = item.name() else {
let Some(attr_name @ (sym::hide | sym::show)) = item.name() else {
self.tcx.emit_node_span_lint(
INVALID_DOC_ATTRIBUTES,
hir_id,
@ -1185,36 +1185,21 @@ impl<'tcx> CheckAttrVisitor<'tcx> {
);
continue;
};
if attr_name != sym::hide && attr_name != sym::show {
self.tcx.emit_node_span_lint(
INVALID_DOC_ATTRIBUTES,
hir_id,
meta.span,
errors::DocAutoCfgExpectsHideOrShow,
);
} else if let Some(list) = item.meta_item_list() {
if let Some(list) = item.meta_item_list() {
for item in list {
if item.meta_item_list().is_some() {
let valid = item.meta_item().is_some_and(|meta| {
meta.path.segments.len() == 1
&& matches!(
&meta.kind,
MetaItemKind::Word | MetaItemKind::NameValue(_)
)
});
if !valid {
self.tcx.emit_node_span_lint(
INVALID_DOC_ATTRIBUTES,
hir_id,
item.span(),
errors::DocAutoCfgHideShowUnexpectedItem {
attr_name: attr_name.as_str(),
},
);
} else if match item {
MetaItemInner::Lit(_) => true,
// We already checked above that it's not a list.
MetaItemInner::MetaItem(meta) => meta.path.segments.len() != 1,
} {
self.tcx.emit_node_span_lint(
INVALID_DOC_ATTRIBUTES,
hir_id,
item.span(),
errors::DocAutoCfgHideShowUnexpectedItem {
attr_name: attr_name.as_str(),
},
errors::DocAutoCfgHideShowUnexpectedItem { attr_name },
);
}
}
@ -1223,7 +1208,7 @@ impl<'tcx> CheckAttrVisitor<'tcx> {
INVALID_DOC_ATTRIBUTES,
hir_id,
meta.span,
errors::DocAutoCfgHideShowExpectsList { attr_name: attr_name.as_str() },
errors::DocAutoCfgHideShowExpectsList { attr_name },
);
}
}

8
compiler/rustc_passes/src/errors.rs
View file

@ -318,14 +318,14 @@ pub(crate) struct DocAutoCfgExpectsHideOrShow;
#[derive(LintDiagnostic)]
#[diag(passes_doc_auto_cfg_hide_show_expects_list)]
pub(crate) struct DocAutoCfgHideShowExpectsList<'a> {
pub attr_name: &'a str,
pub(crate) struct DocAutoCfgHideShowExpectsList {
pub attr_name: Symbol,
}
#[derive(LintDiagnostic)]
#[diag(passes_doc_auto_cfg_hide_show_unexpected_item)]
pub(crate) struct DocAutoCfgHideShowUnexpectedItem<'a> {
pub attr_name: &'a str,
pub(crate) struct DocAutoCfgHideShowUnexpectedItem {
pub attr_name: Symbol,
}
#[derive(LintDiagnostic)]

1
compiler/rustc_span/src/symbol.rs
View file

@ -629,7 +629,6 @@ symbols! {
cfg_emscripten_wasm_eh,
cfg_eval,
cfg_fmt_debug,
cfg_hide,
cfg_overflow_checks,
cfg_panic,
cfg_relocation_model,

42
src/doc/rustdoc/src/unstable-features.md
View file

@ -720,9 +720,9 @@ pass `--doctest-build-arg ARG` for each argument `ARG`.
This flag enables the generation of toggles to expand macros in the HTML source code pages.
## `#[doc(cfg)]`
## `#[doc(cfg)]` and `#[doc(auto_cfg)]`
This feature aims at providing rustdoc users the possibility to add visual markers to the rendered documentation to know under which conditions an item is available (currently possible through the following unstable features: `doc_cfg`, `doc_auto_cfg` and `doc_cfg_hide`).
This feature aims at providing rustdoc users the possibility to add visual markers to the rendered documentation to know under which conditions an item is available (currently possible through the following unstable feature: `doc_cfg`).
It does not aim to allow having a same item with different `cfg`s to appear more than once in the generated documentation.
@ -736,25 +736,6 @@ This features adds the following attributes:
All of these attributes can be added to a module or to the crate root, and they will be inherited by the child items unless another attribute overrides it. This is why "opposite" attributes like `auto_cfg(hide(...))` and `auto_cfg(show(...))` are provided: they allow a child item to override its parent.
### `#[doc(auto_cfg)`/`#[doc(auto_cfg = true)]`/`#[doc(auto_cfg = false)]`
By default, `#[doc(auto_cfg)]` is enabled at the crate-level. When it's enabled, Rustdoc will automatically display `cfg(...)` compatibility information as-if the same `#[doc(cfg(...))]` had been specified.
This attribute impacts the item on which it is used and its descendants.
So if we take back the previous example:
```rust
#[cfg(feature = "futures-io")]
pub mod futures {}
```
There's no need to "duplicate" the `cfg` into a `doc(cfg())` to make Rustdoc display it.
In some situations, the detailed conditional compilation rules used to implement the feature might not serve as good documentation (for example, the list of supported platforms might be very long, and it might be better to document them in one place). To turn it off, add the `#[doc(auto_cfg = false)]` attribute on the item.
If no argument is specified (ie `#[doc(auto_cfg)]`), it's the same as writing `#[doc(auto_cfg = true)]`.
### `#[doc(cfg(...))]`
This attribute provides a standardized format to override `#[cfg()]` attributes to document conditionally available items. Example:
@ -927,6 +908,25 @@ Using this attribute will re-enable `auto_cfg` if it was disabled at this locati
pub fn foo() {}
```
### `#[doc(auto_cfg)`/`#[doc(auto_cfg = true)]`/`#[doc(auto_cfg = false)]`
By default, `#[doc(auto_cfg)]` is enabled at the crate-level. When it's enabled, Rustdoc will automatically display `cfg(...)` compatibility information as-if the same `#[doc(cfg(...))]` had been specified.
This attribute impacts the item on which it is used and its descendants.
So if we take back the previous example:
```rust
#[cfg(feature = "futures-io")]
pub mod futures {}
```
There's no need to "duplicate" the `cfg` into a `doc(cfg())` to make Rustdoc display it.
In some situations, the detailed conditional compilation rules used to implement the feature might not serve as good documentation (for example, the list of supported platforms might be very long, and it might be better to document them in one place). To turn it off, add the `#[doc(auto_cfg = false)]` attribute on the item.
If no argument is specified (ie `#[doc(auto_cfg)]`), it's the same as writing `#[doc(auto_cfg = true)]`.
## Inheritance
Rustdoc merges `cfg` attributes from parent modules to its children. For example, in this case, the module `non_unix` will describe the entire compatibility matrix for the module, and not just its directly attached information:

10
src/librustdoc/clean/types.rs
View file

@ -925,7 +925,7 @@ pub(crate) fn hir_attr_lists<'a, I: IntoIterator<Item = &'a hir::Attribute>>(
/// This type keeps track of (doc) cfg information as we go down the item tree.
#[derive(Clone, Debug)]
pub(crate) struct CfgInfo {
/// List of currently active `doc(auto_cfg(hide(...)))` cfgs,minus currently active
/// List of currently active `doc(auto_cfg(hide(...)))` cfgs, minus currently active
/// `doc(auto_cfg(show(...)))` cfgs.
hidden_cfg: FxHashSet<Cfg>,
/// Current computed `cfg`. Each time we enter a new item, this field is updated as well while
@ -942,13 +942,11 @@ pub(crate) struct CfgInfo {
impl Default for CfgInfo {
fn default() -> Self {
Self {
hidden_cfg: [
hidden_cfg: FxHashSet::from_iter([
Cfg::Cfg(sym::test, None),
Cfg::Cfg(sym::doc, None),
Cfg::Cfg(sym::doctest, None),
]
.into_iter()
.collect(),
]),
current_cfg: Cfg::True,
auto_cfg_active: true,
parent_is_doc_cfg: false,
@ -990,7 +988,7 @@ fn handle_auto_cfg_hide_show(
&& let MetaItemKind::List(items) = &item.kind
{
for item in items {
// Cfg parsing errors should already have been reported in `rustc_passes::check_attr`.
// FIXME: Report in case `Cfg::parse` reports an error?
if let Ok(Cfg::Cfg(key, value)) = Cfg::parse(item) {
if is_show {
if let Some(span) = new_hide_attrs.get(&(key, value)) {

3
src/librustdoc/passes/propagate_doc_cfg.rs
View file

@ -97,9 +97,8 @@ impl CfgPropagator<'_, '_> {
//
// Otherwise, `cfg_info` already tracks everything we need so nothing else to do!
if matches!(item.kind, ItemKind::ImplItem(_))
&& let Some(def_id) = item.item_id.as_def_id().and_then(|def_id| def_id.as_local())
&& let Some(mut next_def_id) = item.item_id.as_local_def_id()
{
let mut next_def_id = def_id;
while let Some(parent_def_id) = self.cx.tcx.opt_local_parent(next_def_id) {
let x = load_attrs(self.cx, parent_def_id.to_def_id());
add_only_cfg_attributes(&mut attrs, x);