From 962b0f19bfd7ce46db842a8271e0497cdfdea7a4 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 19 Aug 2025 12:48:22 -0500 Subject: [PATCH 1/5] docs(style): Specify the frontmatter style Taken from [a style team discussion](https://github.com/rust-lang/style-team/issues/212#issuecomment-3185911143). Assumptions on my part: - I don't need to specify the lack of trailing spaces after the code fence / infostring - We aren't specifying when to include the infostring (one idea being if there is no shebang) - Keep it simple and have a single example instead of showing allowed several variations --- src/doc/style-guide/src/nightly.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/src/doc/style-guide/src/nightly.md b/src/doc/style-guide/src/nightly.md index 66e7fa3c9f89c..608dbd37192a3 100644 --- a/src/doc/style-guide/src/nightly.md +++ b/src/doc/style-guide/src/nightly.md @@ -5,3 +5,29 @@ This chapter documents style and formatting for nightly-only syntax. The rest of Style and formatting for nightly-only syntax should be removed from this chapter and integrated into the appropriate sections of the style guide at the time of stabilization. There is no guarantee of the stability of this chapter in contrast to the rest of the style guide. Refer to the style team policy for nightly formatting procedure regarding breaking changes to this chapter. + +### Frontmatter + +*Location: Placed before comments and attributes in the [root](index.html).* + +*Tracking issue: [#136889](https://github.com/rust-lang/rust/issues/136889)* + +*Feature gate: `frontmatter`* + +There should be no blank lines between the frontmatter and either the start of the file or a shebang. +There can be zero or one line between the frontmatter and any following content. + +The frontmatter fences should use the minimum number of dashes necessary for the contained content (one more than the longest series of initial dashes in the +content, with a minimum of 3 to be recognized as frontmatter delimiters). +If an infostring is present after the opening fence, there should be one space separating them. +The frontmatter fence lines should not have trailing whitespace. + +```rust +#!/usr/bin/env cargo +--- cargo +[dependencies] +regex = "1" +--- + +fn main() {} +``` From d66647ba2c73c353461ceb34f2501496f1576aa1 Mon Sep 17 00:00:00 2001 From: Noratrieb <48135649+Noratrieb@users.noreply.github.com> Date: Fri, 17 Oct 2025 23:28:54 +0200 Subject: [PATCH 2/5] Reword unstable finterprint ICE to ask for reproduction When the unstable finterprint error was added, Rust was on fire, and we needed a quick way for people to sort of understand what's going on, follow the tracking issue, and leave some information without overwhelming the issue tracker and focusing on getting their code working. This is what motivated the previous message. It called this a "known issue", provided help on how to fix it, and only secondarily asked for a bug report. This is no longer true. These days incremental compilation is fairly solid and these issues are supposed to be rare, we expect *none* of them to exist (but obviously know that's not true). As such, it's time to reword this message. Recently someone mentioned how they didn't bother reporting this issue because it said that it was a "known issue", and I only got awareness of their problem because they complained about all the rustc-ice files hanging around their directories. This is not at all what we want, we want reports from people, ideally with a reproduction. To get this, I reworded the error. It now explicitly asks for a reproduction (and explaining what that means) and no longer calls it a "known issue". It also does not link to the tracking issue anymore, because I don't think this tracking issue is useful. It should probably be closed. I still mention the workaround, but explicitly call it a "workaround". People should report a reproduction and only *then* use the workaround. --- compiler/rustc_query_system/messages.ftl | 5 +++-- compiler/rustc_query_system/src/error.rs | 3 ++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/compiler/rustc_query_system/messages.ftl b/compiler/rustc_query_system/messages.ftl index f686608034cba..d2ab2d34c5fcc 100644 --- a/compiler/rustc_query_system/messages.ftl +++ b/compiler/rustc_query_system/messages.ftl @@ -16,10 +16,11 @@ query_system_cycle_stack_single = ...which immediately requires {$stack_bottom} query_system_cycle_usage = cycle used when {$usage} query_system_increment_compilation = internal compiler error: encountered incremental compilation error with {$dep_node} - .help = This is a known issue with the compiler. Run {$run_cmd} to allow your project to compile query_system_increment_compilation_note1 = please follow the instructions below to create a bug report with the provided information -query_system_increment_compilation_note2 = see for more information +query_system_increment_compilation_note2 = for incremental compilation bugs, having a reproduction is vital +query_system_increment_compilation_note3 = an ideal reproduction consists of the code before and some patch that then triggers the bug when applied and compiled again +query_system_increment_compilation_note4 = as a workaround, you can run {$run_cmd} to allow your project to compile query_system_overflow_note = query depth increased by {$depth} when {$desc} diff --git a/compiler/rustc_query_system/src/error.rs b/compiler/rustc_query_system/src/error.rs index 2778b24e7741b..96998c7986897 100644 --- a/compiler/rustc_query_system/src/error.rs +++ b/compiler/rustc_query_system/src/error.rs @@ -69,9 +69,10 @@ pub(crate) struct Reentrant; #[derive(Diagnostic)] #[diag(query_system_increment_compilation)] -#[help] #[note(query_system_increment_compilation_note1)] #[note(query_system_increment_compilation_note2)] +#[note(query_system_increment_compilation_note3)] +#[note(query_system_increment_compilation_note4)] pub(crate) struct IncrementCompilation { pub run_cmd: String, pub dep_node: String, From ebd3220b2081077870e5861782d17ac269a1d0eb Mon Sep 17 00:00:00 2001 From: Jonathan Brouwer Date: Wed, 22 Oct 2025 15:45:47 +0200 Subject: [PATCH 3/5] Remove unused field `style` from `AttributeKind::CrateName` Signed-off-by: Jonathan Brouwer --- compiler/rustc_attr_parsing/src/attributes/crate_level.rs | 7 +------ compiler/rustc_hir/src/attrs/data_structures.rs | 2 +- 2 files changed, 2 insertions(+), 7 deletions(-) diff --git a/compiler/rustc_attr_parsing/src/attributes/crate_level.rs b/compiler/rustc_attr_parsing/src/attributes/crate_level.rs index 20ec0fd0c7b63..1d3ab76e14990 100644 --- a/compiler/rustc_attr_parsing/src/attributes/crate_level.rs +++ b/compiler/rustc_attr_parsing/src/attributes/crate_level.rs @@ -20,12 +20,7 @@ impl SingleAttributeParser for CrateNameParser { return None; }; - Some(AttributeKind::CrateName { - name, - name_span: n.value_span, - attr_span: cx.attr_span, - style: cx.attr_style, - }) + Some(AttributeKind::CrateName { name, name_span: n.value_span, attr_span: cx.attr_span }) } } diff --git a/compiler/rustc_hir/src/attrs/data_structures.rs b/compiler/rustc_hir/src/attrs/data_structures.rs index 4b7894f88e3b7..828c15cc391dd 100644 --- a/compiler/rustc_hir/src/attrs/data_structures.rs +++ b/compiler/rustc_hir/src/attrs/data_structures.rs @@ -499,7 +499,7 @@ pub enum AttributeKind { Coverage(Span, CoverageAttrKind), /// Represents `#[crate_name = ...]` - CrateName { name: Symbol, name_span: Span, attr_span: Span, style: AttrStyle }, + CrateName { name: Symbol, name_span: Span, attr_span: Span }, /// Represents `#[custom_mir]`. CustomMir(Option<(MirDialect, Span)>, Option<(MirPhase, Span)>, Span), From 21db004f585bf1477760556c0b9d0d11199f6643 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 22 Oct 2025 16:58:35 +0200 Subject: [PATCH 4/5] Fix invalid jump to def link generated on derive attributes --- src/librustdoc/html/render/span_map.rs | 3 +-- tests/rustdoc/jump-to-def-assoc-items.rs | 3 +++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/src/librustdoc/html/render/span_map.rs b/src/librustdoc/html/render/span_map.rs index bc9417b1bb1de..257f5da877b56 100644 --- a/src/librustdoc/html/render/span_map.rs +++ b/src/librustdoc/html/render/span_map.rs @@ -7,7 +7,6 @@ use rustc_hir::intravisit::{self, Visitor, VisitorExt}; use rustc_hir::{ExprKind, HirId, Item, ItemKind, Mod, Node, QPath}; use rustc_middle::hir::nested_filter; use rustc_middle::ty::TyCtxt; -use rustc_span::hygiene::MacroKind; use rustc_span::{BytePos, ExpnKind}; use crate::clean::{self, PrimitiveType, rustc_span}; @@ -194,7 +193,7 @@ impl SpanMapVisitor<'_> { } let macro_name = match data.kind { - ExpnKind::Macro(MacroKind::Bang, macro_name) => macro_name, + ExpnKind::Macro(_, macro_name) => macro_name, // Even though we don't handle this kind of macro, this `data` still comes from // expansion so we return `true` so we don't go any deeper in this code. _ => return true, diff --git a/tests/rustdoc/jump-to-def-assoc-items.rs b/tests/rustdoc/jump-to-def-assoc-items.rs index 8cbf990628386..0dfe3c7bdc155 100644 --- a/tests/rustdoc/jump-to-def-assoc-items.rs +++ b/tests/rustdoc/jump-to-def-assoc-items.rs @@ -26,6 +26,9 @@ impl C { pub fn wat() {} } +//@ has - '//a[@href="{{channel}}/core/fmt/macros/macro.Debug.html"]' 'Debug' +//@ has - '//a[@href="{{channel}}/core/cmp/macro.PartialEq.html"]' 'PartialEq' +#[derive(Debug, PartialEq)] pub struct Bar; impl Trait for Bar { type T = Foo; From e1e851dc57793e8320324da37958489d50ada8dc Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 22 Oct 2025 17:32:20 +0200 Subject: [PATCH 5/5] [rustdoc] Check `doc(cfg())` even of private/hidden items --- src/librustdoc/passes/mod.rs | 2 +- tests/rustdoc-ui/invalid-cfg.rs | 17 ++++++++++ tests/rustdoc-ui/invalid-cfg.stderr | 38 +++++++++++++++++++++- tests/rustdoc-ui/issues/issue-91713.stdout | 2 +- 4 files changed, 56 insertions(+), 3 deletions(-) diff --git a/src/librustdoc/passes/mod.rs b/src/librustdoc/passes/mod.rs index 856581e0d033e..a1e8e75306235 100644 --- a/src/librustdoc/passes/mod.rs +++ b/src/librustdoc/passes/mod.rs @@ -95,11 +95,11 @@ pub(crate) const DEFAULT_PASSES: &[ConditionalPass] = &[ ConditionalPass::always(CHECK_DOC_TEST_VISIBILITY), ConditionalPass::always(CHECK_DOC_CFG), ConditionalPass::always(STRIP_ALIASED_NON_LOCAL), + ConditionalPass::always(PROPAGATE_DOC_CFG), ConditionalPass::new(STRIP_HIDDEN, WhenNotDocumentHidden), ConditionalPass::new(STRIP_PRIVATE, WhenNotDocumentPrivate), ConditionalPass::new(STRIP_PRIV_IMPORTS, WhenDocumentPrivate), ConditionalPass::always(COLLECT_INTRA_DOC_LINKS), - ConditionalPass::always(PROPAGATE_DOC_CFG), ConditionalPass::always(PROPAGATE_STABILITY), ConditionalPass::always(RUN_LINTS), ]; diff --git a/tests/rustdoc-ui/invalid-cfg.rs b/tests/rustdoc-ui/invalid-cfg.rs index aff36286c535c..7e54aeea1defb 100644 --- a/tests/rustdoc-ui/invalid-cfg.rs +++ b/tests/rustdoc-ui/invalid-cfg.rs @@ -2,3 +2,20 @@ #[doc(cfg = "x")] //~ ERROR not followed by parentheses #[doc(cfg(x, y))] //~ ERROR multiple `cfg` predicates pub struct S {} + +// We check it also fails on private items. +#[doc(cfg = "x")] //~ ERROR not followed by parentheses +#[doc(cfg(x, y))] //~ ERROR multiple `cfg` predicates +struct X {} + +// We check it also fails on hidden items. +#[doc(cfg = "x")] //~ ERROR not followed by parentheses +#[doc(cfg(x, y))] //~ ERROR multiple `cfg` predicates +#[doc(hidden)] +pub struct Y {} + +// We check it also fails on hidden AND private items. +#[doc(cfg = "x")] //~ ERROR not followed by parentheses +#[doc(cfg(x, y))] //~ ERROR multiple `cfg` predicates +#[doc(hidden)] +struct Z {} diff --git a/tests/rustdoc-ui/invalid-cfg.stderr b/tests/rustdoc-ui/invalid-cfg.stderr index dae238b052b8a..455626e07bd58 100644 --- a/tests/rustdoc-ui/invalid-cfg.stderr +++ b/tests/rustdoc-ui/invalid-cfg.stderr @@ -10,5 +10,41 @@ error: multiple `cfg` predicates are specified LL | #[doc(cfg(x, y))] | ^ -error: aborting due to 2 previous errors +error: `cfg` is not followed by parentheses + --> $DIR/invalid-cfg.rs:7:7 + | +LL | #[doc(cfg = "x")] + | ^^^^^^^^^ help: expected syntax is: `cfg(/* predicate */)` + +error: multiple `cfg` predicates are specified + --> $DIR/invalid-cfg.rs:8:14 + | +LL | #[doc(cfg(x, y))] + | ^ + +error: `cfg` is not followed by parentheses + --> $DIR/invalid-cfg.rs:12:7 + | +LL | #[doc(cfg = "x")] + | ^^^^^^^^^ help: expected syntax is: `cfg(/* predicate */)` + +error: multiple `cfg` predicates are specified + --> $DIR/invalid-cfg.rs:13:14 + | +LL | #[doc(cfg(x, y))] + | ^ + +error: `cfg` is not followed by parentheses + --> $DIR/invalid-cfg.rs:18:7 + | +LL | #[doc(cfg = "x")] + | ^^^^^^^^^ help: expected syntax is: `cfg(/* predicate */)` + +error: multiple `cfg` predicates are specified + --> $DIR/invalid-cfg.rs:19:14 + | +LL | #[doc(cfg(x, y))] + | ^ + +error: aborting due to 8 previous errors diff --git a/tests/rustdoc-ui/issues/issue-91713.stdout b/tests/rustdoc-ui/issues/issue-91713.stdout index 7254708157f0e..c0cd454e8f3ad 100644 --- a/tests/rustdoc-ui/issues/issue-91713.stdout +++ b/tests/rustdoc-ui/issues/issue-91713.stdout @@ -17,11 +17,11 @@ Default passes for rustdoc: check_doc_test_visibility check-doc-cfg strip-aliased-non-local + propagate-doc-cfg strip-hidden (when not --document-hidden-items) strip-private (when not --document-private-items) strip-priv-imports (when --document-private-items) collect-intra-doc-links - propagate-doc-cfg propagate-stability run-lints