Skip to content

Implement RFC 3631: add rustdoc doc_cfg features #138907

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 10 commits into
base: master
Choose a base branch
from
+961 −366
Open

Implement RFC 3631: add rustdoc doc_cfg features #138907

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
f3c5653
Implement RFC 3631
GuillaumeGomez Mar 28, 2025
746014a
Update rustdoc tests
GuillaumeGomez Mar 28, 2025
939427f
Add "global" rustdoc test for RFC 3631
GuillaumeGomez Apr 1, 2025
31e92eb
Strenghten checks for `doc(auto_cfg(show/hide))` attributes
GuillaumeGomez Apr 1, 2025
bedfc2b
Remove useless code in `propagate_doc_cfg.rs`
GuillaumeGomez Apr 1, 2025
d3f2026
Remove ui test for doc_cfg feature gate
GuillaumeGomez Apr 7, 2025
a6ebfe4
Remove `doc_cfg` related content from rustdoc book unstable features …
GuillaumeGomez Apr 7, 2025
341f307
Update book for `doc_cfg` feature
GuillaumeGomez Apr 11, 2025
ccc2074
Rename `CfgInfo::doc_auto_cfg_active` into `auto_cfg_active`
GuillaumeGomez Apr 11, 2025
1a0781f
Put back the `doc_cfg` code behind a nightly feature
GuillaumeGomez Apr 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion compiler/rustc_ast_passes/src/feature_gate.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,6 @@ impl<'a> Visitor<'a> for PostExpansionVisitor<'a> {
gate_doc!(
"experimental" {
cfg => doc_cfg
cfg_hide => doc_cfg_hide
masked => doc_masked
notable_trait => doc_notable_trait
}
Expand Down
13 changes: 11 additions & 2 deletions compiler/rustc_passes/messages.ftl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -182,8 +182,17 @@ passes_doc_alias_start_end =
passes_doc_attr_not_crate_level =
`#![doc({$attr_name} = "...")]` isn't allowed as a crate-level attribute

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(...))]"`

passes_doc_auto_cfg_hide_show_expects_list =
`#![doc(auto_cfg({$attr_name}(...)))]` only expects a list of items

passes_doc_auto_cfg_hide_show_unexpected_item =
`#![doc(auto_cfg({$attr_name}(...)))]` only accepts identifiers or key/values items

passes_doc_auto_cfg_wrong_literal =
`expected boolean for #[doc(auto_cfg = ...)]`

passes_doc_expect_str =
doc {$attr_name} attribute expects a string: #[doc({$attr_name} = "a")]
Expand Down
66 changes: 52 additions & 14 deletions compiler/rustc_passes/src/check_attr.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1276,16 +1276,56 @@ impl<'tcx> CheckAttrVisitor<'tcx> {
}
}

/// Check that the `#![doc(cfg_hide(...))]` attribute only contains a list of attributes.
///
fn check_doc_cfg_hide(&self, meta: &MetaItemInner, hir_id: HirId) {
if meta.meta_item_list().is_none() {
self.tcx.emit_node_span_lint(
INVALID_DOC_ATTRIBUTES,
hir_id,
meta.span(),
errors::DocCfgHideTakesList,
);
/// Check that the `#![doc(auto_cfg(..))]` attribute has expected input.
fn check_doc_auto_cfg(&self, meta: &MetaItemInner, hir_id: HirId) {
let MetaItemInner::MetaItem(meta) = meta else {
unreachable!();
};
match &meta.kind {
MetaItemKind::Word => {}
MetaItemKind::NameValue(lit) => {
if !matches!(lit.kind, LitKind::Bool(_)) {
self.tcx.emit_node_span_lint(
INVALID_DOC_ATTRIBUTES,
hir_id,
meta.span,
errors::DocAutoCfgWrongLiteral,
);
}
}
MetaItemKind::List(list) => {
for item in list {
let attr_name = item.name_or_empty();
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() {
for item in list {
if item.meta_item_list().is_some() {
self.tcx.emit_node_span_lint(
INVALID_DOC_ATTRIBUTES,
hir_id,
item.span(),
errors::DocAutoCfgHideShowUnexpectedItem {
attr_name: attr_name.as_str(),
},
);
}
}
} else {
self.tcx.emit_node_span_lint(
INVALID_DOC_ATTRIBUTES,
hir_id,
meta.span,
errors::DocAutoCfgHideShowExpectsList { attr_name: attr_name.as_str() },
);
}
}
}
}
}

Expand Down Expand Up @@ -1346,10 +1386,8 @@ impl<'tcx> CheckAttrVisitor<'tcx> {
self.check_attr_crate_level(attr, meta, hir_id);
}

sym::cfg_hide => {
Copy link
Member

Choose a reason for hiding this comment

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

Should we delete sym::cfg_hide as well? Or is it used somewhere else?

Copy link
Member Author

Choose a reason for hiding this comment

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

As far as I can see, it's not used anywhere else.

if self.check_attr_crate_level(attr, meta, hir_id) {
self.check_doc_cfg_hide(meta, hir_id);
}
sym::auto_cfg => {
self.check_doc_auto_cfg(meta, hir_id);
}

sym::inline | sym::no_inline => {
Expand Down
20 changes: 18 additions & 2 deletions compiler/rustc_passes/src/errors.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -333,8 +333,24 @@ pub(crate) struct DocTestLiteral;
pub(crate) struct DocTestTakesList;

#[derive(LintDiagnostic)]
#[diag(passes_doc_cfg_hide_takes_list)]
pub(crate) struct DocCfgHideTakesList;
#[diag(passes_doc_auto_cfg_wrong_literal)]
pub(crate) struct DocAutoCfgWrongLiteral;

#[derive(LintDiagnostic)]
#[diag(passes_doc_auto_cfg_expects_hide_or_show)]
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,
}

#[derive(LintDiagnostic)]
#[diag(passes_doc_auto_cfg_hide_show_unexpected_item)]
pub(crate) struct DocAutoCfgHideShowUnexpectedItem<'a> {
pub attr_name: &'a str,
}

#[derive(LintDiagnostic)]
#[diag(passes_doc_test_unknown_any)]
Expand Down
4 changes: 4 additions & 0 deletions compiler/rustc_span/src/symbol.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -534,6 +534,7 @@ symbols! {
attributes,
audit_that,
augmented_assignments,
auto_cfg,
auto_traits,
autodiff,
automatically_derived,
Expand Down Expand Up @@ -1103,6 +1104,8 @@ symbols! {
hashset_iter_ty,
hexagon_target_feature,
hidden,
hidden_cfg,
hide,
hint,
homogeneous_aggregate,
host,
Expand Down Expand Up @@ -1891,6 +1894,7 @@ symbols! {
shl_assign,
shorter_tail_lifetimes,
should_panic,
show,
shr,
shr_assign,
sig_dfl,
Expand Down
32 changes: 23 additions & 9 deletions library/alloc/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,15 +64,29 @@
issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/",
test(no_crate_inject, attr(allow(unused_variables), deny(warnings)))
)]
#![doc(cfg_hide(
not(test),
not(any(test, bootstrap)),
no_global_oom_handling,
not(no_global_oom_handling),
not(no_rc),
not(no_sync),
target_has_atomic = "ptr"
))]
#![cfg_attr(
bootstrap,
doc(cfg_hide(
not(test),
not(any(test, bootstrap)),
no_global_oom_handling,
not(no_global_oom_handling),
not(no_rc),
not(no_sync),
target_has_atomic = "ptr"
))
)]
#![cfg_attr(
not(bootstrap),
doc(auto_cfg(hide(
bootstrap,
no_global_oom_handling,
no_global_oom_handling,
no_rc,
no_sync,
target_has_atomic = "ptr"
)))
)]
#![doc(rust_logo)]
#![feature(rustdoc_internals)]
#![no_std]
Expand Down
69 changes: 48 additions & 21 deletions library/core/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,27 +51,54 @@
test(attr(allow(dead_code, deprecated, unused_variables, unused_mut)))
)]
#![doc(rust_logo)]
#![doc(cfg_hide(
no_fp_fmt_parse,
target_pointer_width = "16",
target_pointer_width = "32",
target_pointer_width = "64",
target_has_atomic = "8",
target_has_atomic = "16",
target_has_atomic = "32",
target_has_atomic = "64",
target_has_atomic = "ptr",
target_has_atomic_equal_alignment = "8",
target_has_atomic_equal_alignment = "16",
target_has_atomic_equal_alignment = "32",
target_has_atomic_equal_alignment = "64",
target_has_atomic_equal_alignment = "ptr",
target_has_atomic_load_store = "8",
target_has_atomic_load_store = "16",
target_has_atomic_load_store = "32",
target_has_atomic_load_store = "64",
target_has_atomic_load_store = "ptr",
))]
#![cfg_attr(
bootstrap,
doc(cfg_hide(
no_fp_fmt_parse,
target_pointer_width = "16",
target_pointer_width = "32",
target_pointer_width = "64",
target_has_atomic = "8",
target_has_atomic = "16",
target_has_atomic = "32",
target_has_atomic = "64",
target_has_atomic = "ptr",
target_has_atomic_equal_alignment = "8",
target_has_atomic_equal_alignment = "16",
target_has_atomic_equal_alignment = "32",
target_has_atomic_equal_alignment = "64",
target_has_atomic_equal_alignment = "ptr",
target_has_atomic_load_store = "8",
target_has_atomic_load_store = "16",
target_has_atomic_load_store = "32",
target_has_atomic_load_store = "64",
target_has_atomic_load_store = "ptr",
))
)]
#![cfg_attr(
not(bootstrap),
doc(auto_cfg(hide(
no_fp_fmt_parse,
target_pointer_width = "16",
target_pointer_width = "32",
target_pointer_width = "64",
target_has_atomic = "8",
target_has_atomic = "16",
target_has_atomic = "32",
target_has_atomic = "64",
target_has_atomic = "ptr",
target_has_atomic_equal_alignment = "8",
target_has_atomic_equal_alignment = "16",
target_has_atomic_equal_alignment = "32",
target_has_atomic_equal_alignment = "64",
target_has_atomic_equal_alignment = "ptr",
target_has_atomic_load_store = "8",
target_has_atomic_load_store = "16",
target_has_atomic_load_store = "32",
target_has_atomic_load_store = "64",
target_has_atomic_load_store = "ptr",
)))
)]
#![no_core]
#![rustc_coherence_is_core]
#![rustc_preserve_ub_checks]
Expand Down
16 changes: 10 additions & 6 deletions library/std/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -235,12 +235,16 @@
test(attr(allow(dead_code, deprecated, unused_variables, unused_mut)))
)]
#![doc(rust_logo)]
#![doc(cfg_hide(
not(test),
not(any(test, bootstrap)),
no_global_oom_handling,
not(no_global_oom_handling)
))]
#![cfg_attr(
bootstrap,
doc(cfg_hide(
not(test),
not(any(test, bootstrap)),
no_global_oom_handling,
not(no_global_oom_handling)
))
)]
#![cfg_attr(not(bootstrap), doc(auto_cfg(hide(bootstrap, no_global_oom_handling,))))]
// Don't link to std. We are std.
#![no_std]
// Tell the compiler to link to either panic_abort or panic_unwind
Expand Down
Loading
Loading