Skip to content

Commit ef36323

Browse files
JonathanBrouwerJonathanBrouwer
authored
Rollup merge of #159636 - nnethercote:some-comments, r=petrochenkov
Improve some comments (and an error message) Details in individual commits. r? @petrochenkov
2 parents 82d262f + c266b1c commit ef36323

5 files changed

Lines changed: 56 additions & 14 deletions

File tree

‎compiler/rustc_ast/src/ast.rs‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3413,6 +3413,29 @@ pub struct Attribute {
34133413
/// Denotes if the attribute decorates the following construct (outer)
34143414
/// or the construct this attribute is contained within (inner).
34153415
pub style: AttrStyle,
3416+
3417+
/// The carets in the examples below show the spans for various cases.
3418+
/// ```text
3419+
/// #[foo] - A vanilla parsed attribute.
3420+
/// ^^^^^^ - Its span covers it all.
3421+
///
3422+
/// /** abc */ /// xyz - A parsed doc comment.
3423+
/// ^^^^^^^^^^ ^^^^^^^ - Its span covers the text and comment marker(s).
3424+
/// - The same span is also used if the doc comment is desugared (into
3425+
/// a new normal `#[doc = r"..."]` attribute) by
3426+
/// `desugar_doc_comments` before being passed to a macro (which
3427+
/// is done so that `#[$m:meta]` will match).
3428+
///
3429+
/// #[cfg_attr(pred, foo)] - A parsed `cfg_attr` attribute.
3430+
/// ^^^^^^^^^^^^^^^^^^^^^^ - Its span covers it all.
3431+
/// ^^^ - Span of the new replacement attribute (equivalent to `#[foo]`)
3432+
/// created by `cfg_attr` expansion (if `pred` is true).
3433+
/// ^^^^^^^^^^^^^^^^^^^^^^ - Span of the synthetic `CfgAttrTrace` attribute created by
3434+
/// `cfg_attr` expansion. (`CfgTrace` is derived from `#[cfg(..)]` and
3435+
/// handled similarly.)
3436+
/// ```
3437+
/// Finally, for compiler-generated attributes the span is whatever the construction site
3438+
/// chooses. Usually `DUMMY_SP` or some relevant span from the source code.
34163439
pub span: Span,
34173440
}
34183441

‎compiler/rustc_expand/src/base.rs‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,11 @@ use crate::mbe::macro_rules::ParserAnyMacro;
3838
use crate::module::DirOwnership;
3939
use crate::stats::MacroStat;
4040

41-
// When adding new variants, make sure to
42-
// adjust the `visit_*` / `flat_map_*` calls in `InvocationCollector`
43-
// to use `assign_id!`
41+
/// This type encapsulates every AST node that can have attributes, i.e. those
42+
/// nodes with a non-trivial implementation of `HasAttrs`.
43+
///
44+
/// When adding new variants, make sure to adjust the `visit_*` / `flat_map_*`
45+
/// calls in `InvocationCollector` to use `assign_id!`
4446
#[derive(Debug, Clone)]
4547
pub enum Annotatable {
4648
Item(Box<ast::Item>),
@@ -117,6 +119,7 @@ impl Annotatable {
117119
}
118120
}
119121

122+
/// Converts the `Annotatable` to a token stream, e.g. to hand to a proc macro.
120123
pub fn to_tokens(&self) -> TokenStream {
121124
match self {
122125
Annotatable::Item(node) => TokenStream::from_ast(node),

‎compiler/rustc_expand/src/diagnostics.rs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -450,14 +450,14 @@ pub(crate) struct GlobDelegationOutsideImpls {
450450
}
451451

452452
#[derive(Diagnostic)]
453-
#[diag("`crate_name` within an `#![cfg_attr]` attribute is forbidden")]
453+
#[diag("`crate_name` within a `#![cfg_attr]` attribute is forbidden")]
454454
pub(crate) struct CrateNameInCfgAttr {
455455
#[primary_span]
456456
pub span: Span,
457457
}
458458

459459
#[derive(Diagnostic)]
460-
#[diag("`crate_type` within an `#![cfg_attr]` attribute is forbidden")]
460+
#[diag("`crate_type` within a `#![cfg_attr]` attribute is forbidden")]
461461
pub(crate) struct CrateTypeInCfgAttr {
462462
#[primary_span]
463463
pub span: Span,

‎compiler/rustc_parse/src/parser/attr_wrapper.rs‎

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -102,11 +102,27 @@ impl<'a> Parser<'a> {
102102

103103
/// Parses code with `f`. If appropriate, it records the tokens (in
104104
/// `LazyAttrTokenStream` form) that were parsed in the result, accessible
105-
/// via the `HasTokens` trait. The `Trailing` part of the callback's
106-
/// result indicates if an extra token should be captured, e.g. a comma or
107-
/// semicolon. The `UsePreAttrPos` part of the callback's result indicates
108-
/// if we should use `pre_attr_pos` as the collection start position (only
109-
/// required in a few cases).
105+
/// via the `HasTokens` trait.
106+
///
107+
/// Why is this done? Various macro cases require an AST node's tokens.
108+
/// - Proc macros: all proc macros take a token stream.
109+
/// - Function-style proc macros (`foo!(..)`): these can receive a token
110+
/// stream without any parsing occurring within the parentheses.
111+
/// - Attribute macros (`#[foo]`): at parse time (pre-resolution) we
112+
/// don't know if a non-builtin `#[foo]` is an attribute proc macro, so
113+
/// the parser does a full parse and collects tokens (lazily) in case.
114+
/// - Derive macros (`derive(Foo)`): any input with
115+
/// `#[cfg]`/`#[cfg_attr]` must be stripped before being passed to the
116+
/// derive macro, which requires parsing. Identifying the end of the
117+
/// item also requires parsing.
118+
/// - Decl macros: a matched nonterminal (e.g. `$e:expr`) needs tokens in
119+
/// case it is passed into a proc macro.
120+
///
121+
/// The `Trailing` part of the callback's result indicates if an extra
122+
/// token should be captured, e.g. a comma or semicolon. The
123+
/// `UsePreAttrPos` part of the callback's result indicates if we should
124+
/// use `pre_attr_pos` as the collection start position (only required in a
125+
/// few cases).
110126
///
111127
/// The `attrs` passed in are in `AttrWrapper` form, which is opaque. The
112128
/// `AttrVec` within is passed to `f`. See the comment on `AttrWrapper` for

‎tests/ui/cfg/crate-attributes-using-cfg_attr.stderr‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,24 @@
1-
error: `crate_type` within an `#![cfg_attr]` attribute is forbidden
1+
error: `crate_type` within a `#![cfg_attr]` attribute is forbidden
22
--> $DIR/crate-attributes-using-cfg_attr.rs:5:18
33
|
44
LL | #![cfg_attr(foo, crate_type="bin")]
55
| ^^^^^^^^^^^^^^^^
66

7-
error: `crate_name` within an `#![cfg_attr]` attribute is forbidden
7+
error: `crate_name` within a `#![cfg_attr]` attribute is forbidden
88
--> $DIR/crate-attributes-using-cfg_attr.rs:8:18
99
|
1010
LL | #![cfg_attr(foo, crate_name="bar")]
1111
| ^^^^^^^^^^^^^^^^
1212

13-
error: `crate_type` within an `#![cfg_attr]` attribute is forbidden
13+
error: `crate_type` within a `#![cfg_attr]` attribute is forbidden
1414
--> $DIR/crate-attributes-using-cfg_attr.rs:5:18
1515
|
1616
LL | #![cfg_attr(foo, crate_type="bin")]
1717
| ^^^^^^^^^^^^^^^^
1818
|
1919
= note: duplicate diagnostic emitted due to `-Z deduplicate-diagnostics=no`
2020

21-
error: `crate_name` within an `#![cfg_attr]` attribute is forbidden
21+
error: `crate_name` within a `#![cfg_attr]` attribute is forbidden
2222
--> $DIR/crate-attributes-using-cfg_attr.rs:8:18
2323
|
2424
LL | #![cfg_attr(foo, crate_name="bar")]

0 commit comments

Comments
 (0)