Refactor rustc_attr_data_structures documentation
#142082
Conversation
rustbot
added
A-attributes
|
Some changes occurred in compiler/rustc_attr_data_structures |
xizheyin
force-pushed
the
rustc_attr_data_structures
branch
from
ff9276d to
1cf957f
Compare
| /// The word "parsed" could be a little misleading here, because the parser already parses | ||
| /// attributes early on. However, the result, an [`ast::Attribute`] | ||
| /// is only parsed at a high level, still containing a token stream in many cases. That is | ||
| /// because the structure of the contents varies from attribute to attribute. | ||
| /// With a parsed attribute I mean that each attribute is processed individually into a | ||
| /// final structure, which on-site (the place where the attribute is useful for, think the | ||
| /// the place where `must_use` is checked) little to no extra parsing or validating needs to | ||
| /// happen. |
There was a problem hiding this comment.
By adding Note on Attribute Organization, we don't have to explain the meaning of parsed as we did. It would be clearer.
| /// [`rustc_attr_parsing`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_attr_parsing/index.html | ||
| #[derive(Clone, Debug, HashStable_Generic, Encodable, Decodable, PrintAttribute)] | ||
| pub enum AttributeKind { | ||
| // tidy-alphabetical-start | ||
| /// Allows unstable features in const functions. |
There was a problem hiding this comment.
I just approved someone else's PR that added this same documentation, it was briefer, but I'd actually say that's alright. Before we merge this let's wait on that one (#140372) and then I'll decide whether it's better to have this. This is quite a lot of repeated typing for every new attribute, but it's nice to have them documented somewhere too. That place might not be here though. Alas, for that reason I won't quite approve this PR
There was a problem hiding this comment.
Some day we might be able to parse these comments and use a derive macro to document them (and use them as templates for diags? Something similar but worse already happens so we'll see)
There was a problem hiding this comment.
Yes, there is some repetitive work here，and it looks heavy.My original intention in writing this document is, many developers can't understand all these macros, so they need to search everywhere to understand their functions when reading this code.
But it's a good idea to use macros to eliminate duplication of work. I'll delete it here first. Comments with examples with macros should be meaningful to many enumerations in rustc C. Can we add it as a separate function?
| @@ -1,3 +1,37 @@ | |||
| //! Data structures for representing parsed attributes in the Rust compiler. | |||
| //! | |||
| //! This crate is part of a series of crates that handle attribute processing: | |||
There was a problem hiding this comment.
It seems like this can easily get out-of-date. I'd prefer a reference to attr parsing here and to centralize all docs there. The story is rather similar anyway
There was a problem hiding this comment.
That makes sense. Here is a duplicate of that document.
rustbot
added
S-waiting-on-author
Signed-off-by: xizheyin <[email protected]>
xizheyin
force-pushed
the
rustc_attr_data_structures
branch
from
1cf957f to
b867d3e
Compare
| /// Some attributes can be applied multiple times to the same item, and they are "collapsed" into a single | ||
| /// semantic attribute. For example: | ||
| /// ```rust | ||
| /// #[repr(C)] | ||
| /// #[repr(packed)] | ||
| /// struct S { } | ||
| /// ``` | ||
| /// This is equivalent to `#[repr(C, packed)]` and results in a single [`AttributeKind::Repr`] containing | ||
| /// both `C` and `packed` annotations. This collapsing happens during parsing and is reflected in the | ||
| /// data structures defined in this enum. |
There was a problem hiding this comment.
I add repr example to explain "collapsed"
rustbot
added
S-waiting-on-review
I was reading through
AttributeKindand realized that attributes likeInlineAttrdidn't appear in it, however, I found them inrustc_codegen_ssaand understood why (guessing).There's almost no overall documentation for this crate, I've added the organized documentation at the top of
lib.rs, and I've grouped the Attributes into two categories:AttributeKindthat run all through the compiler, and the ones that are only used incodegen_ssa, such asInlineAttr,OptimizeAttr,InstructionSetAttr.Also, I've added documentation for
AttributeKindthat further explains why attributes likeInlineAttrdon't appear in it, with examples for each variant.r? @jdonszelmann