Update attribute documentation. #528

ehuss · 2019-03-01T18:46:20Z

Document unrestricted_attribute_tokens, closes Document unrestricted_attribute_tokens #525
Document tool_attributes, closes Document RFC 2103 tool_attributes #526
Document cfg_attr_multi, closes Document RFC 2539 (#[cfg_attr(p, attr1, attr2)]) #500
Remove linked_from, it was removed in Implement RFC 1717 rust#37973
Remove macro_reexport, it was removed in Remove unstable macro_reexport rust#49982
Remove unstable attributes: linkage, link_args

ehuss · 2019-03-01T18:47:00Z

This explicitly does not talk about attribute name scoping and resolution. That is a much bigger topic that I might tackle separately.

I'm also looking at documenting the syntax for every built-in attribute, better incorporating MetaItem. I think this should be done separately since it will likely be a large change.

Finally, I've noted a number of built-in attributes that are not documented that probably should be. I'll try to follow up on those later.

Can someone clarify the distinction of inert/active attributes? I can't find anything in rustc that tracks that. In what way is that difference ever observable by the user?

petrochenkov · 2019-03-01T20:27:48Z

src/attributes.md

-the bang after the hash, apply to the thing that follows the attribute.
+* Built-in attributes
+* [Macro attributes][attribute macro]
+* [Derive mode helper attributes]


#412 (comment)
I still think "mode" should not be used here.

I agree, "mode" has always seemed strange to me.

petrochenkov · 2019-03-01T20:32:48Z

src/attributes.md

-* Built-in attributes
-* Macro attributes
-* Derive mode helper attributes
+A "meta item" is the syntax used for the _Attr_ rule by built-in attributes


"built-in attributes" -> "most of built-in attributes", this is not a requirement but rather a "tradition" and implementation detail.
cfg_attr for example, doesn't fit into the meta item syntax and may contain attributes with "unrestricted" input inside it.

Also, meta macro fragment not accepting attributes with the unrestricted input is generally a bug / something under-implemented, but I guess the reference needs to describe the actual compiler behavior rather than the intent.

Ah, good point. If it changes, I'll try to make sure this gets updated.

My plan is to expand this section in the future to include some of the common templates you added (like MetaNameValueStr) so that other places in the documentation can just say something like "crate_name uses the MetaNameValueStr syntax to …". When I do that, I might tweak the wording here to make the relationship to built-in attributes clearer.

petrochenkov · 2019-03-01T20:35:37Z

src/attributes.md

+
+// Controls the "cyclomatic complexity" threshold for the cLippy tool.
+#[clippy::cyclomatic_complexity = "100"]
+pub fn f() {}


It probably makes sense to say that only two "tool modules" are currently available - rustfmt and clippy, and both are hard-coded into the compiler, and there's no way to introduce a custom tool module right now.

I thought about that, but I was reluctant to enshrine "clippy" and "rustfmt" as part of the language. I don't want to be too pedantic, but maybe the added note is ok? To me it's a question of the balance of the reference targeting the language vs the rustc implementation.

petrochenkov · 2019-03-01T20:40:28Z

Can someone clarify the distinction of inert/active attributes? I can't find anything in rustc that tracks that. In what way is that difference ever observable by the user?

An active attribute (a macro attribute, cfg, cfg_attr or derive) transforms its input and disappears in the process.
An inert attribute just sits there and waits for being interpreted (by the compiler, or a tool, or a proc macro).

ehuss · 2019-03-01T23:06:45Z

Thanks for the speedy review!

From a language perspective, it seems like the only scenario where the presence/absence of an attribute matters is for attribute and derive macros, right? I've been doing some tests, and it doesn't seem to match my expectations. Attribute macros see cfg attributes if the cfg predicate passes, the cfg isn't removed. If the cfg predicate fails, then everything is pruned before the proc macro gets a chance to run, so that implies that cfg is processed before proc-macros and it should have been removed when it passed. When does a cfg with a passing predicate get removed? How can one write code such that the removal can be observed?

EDIT: I was wrong here, the order of attributes matters. However, test seems to always be "active". When compiling with or without tests, it appears to be removed.
The docs also mention test being either inert or active, but proc-macros see #[test] regardless of whether or not --test is used. Perhaps test runs after proc-macros? In which case, it seems like an unobservable distinction, irrelevant to the language.

I do see that previously processed attribute macros are removed when you have multiple of them.

I want to be clear if Tool Attributes are always inert. I can't find the code where this removal happens, and I can't find a way to observe it (other than the multiple attribute macro situation).

Centril

lgtm; I'll let @petrochenkov sign off on this one.

src/conditional-compilation.md

src/procedural-macros.md

Havvy

Just a cursory look at this, it all looks good to me, with the one suggestion of adding an "only".

Re: "derive mode", I needed a name for each thing you pass to a derive. People are just calling them derive macros, so changing mode->macro would be fine.

src/attributes.md

petrochenkov · 2019-03-02T06:51:32Z

@ehuss

From a language perspective, it seems like the only scenario where the presence/absence of an attribute matters is for attribute and derive macros, right?

I don't understand what this means.
Presence of inert attributes still matters a lot for the language?

cfg is processed before proc-macros

Generally, yes, but in details it's a mess that needs fixing (individual pieces were implemented in different time by different people without understanding the whole picture and having a common "vision").
I have a couple of PRs in the pipeline that'll hopefully land in March, then we'll be able to document how cfg/cfg_attr works relatively to attribute macros and derives.

Attribute macros see cfg attributes if the cfg predicate passes, the cfg isn't removed.

This is an implementation defect, it causes cfg predicates being evaluated multiple times.
At least the predicate result is the same every time (I think) and cfg application is idempotent.
cfg is effectively a macro and it should behave like macro, with exception of the general "early expansion" aspect which we cannot change.

I want to be clear if Tool Attributes are always inert.

The compiler always treats tool attributes as inert.
Tools of course may do anything with them, or with code in general.

petrochenkov · 2019-03-02T07:20:37Z

Meta: looks like I'm now assigned, but I cannot merge PRs in this repo.

Centril · 2019-03-02T07:47:55Z

@petrochenkov Oh; uhmm, just leave a note when you think this is in a good state and someone will merge it. :)

ehuss · 2019-03-02T20:30:14Z

Thanks everyone for taking a look!

@petrochenkov thanks, I think that makes it clearer to me.

I'll follow up with separate PR's for some of the other things noted here.

Co-Authored-By: ehuss <[email protected]>

Update books Update nomicon, reference, book, edition-guide, embedded-book rust-by-example cannot be updated because it is currently broken (rust-lang/rust-by-example#1161) ## nomicon 8 commits in b7eb4a087207af2405c0669fa577f8545b894c66..f1ff93b66844493a7b03101c7df66ac958c62418 2018-11-30 08:52:24 -0500 to 2019-02-26 13:37:28 -0500 - Fix typo in other-reprs.md (rust-lang/nomicon#112) - Remove duplicate 'the' in aliasing.md (rust-lang/nomicon#116) - Fix typo in subtyping.md (rust-lang/nomicon#117) - Trivial updates to the coercions chapter (rust-lang/nomicon#118) - Fix double "the" in aliasing.md (rust-lang/nomicon#119) - Fixes outdated bindgen link (rust-lang/nomicon#110) - Fix link to type layout reference (rust-lang/nomicon#121) - Fix capitalization of Rust in races.md (rust-lang/nomicon#107) ## reference 18 commits in 1c775a1..41493ff 2019-01-13 21:12:05 +0100 to 2019-03-05 12:32:22 +0100 - Fix broken link. (rust-lang/reference#527) - Update attribute documentation. (rust-lang/reference#528) - Remove target_has_atomic. (rust-lang/reference#529) - Remove "mode" from derive macro terminology. (rust-lang/reference#530) - Clarifications (rust-lang/reference#493) - Fix an incorrect note (rust-lang/reference#522) - Document extern_crate_self (rust-lang/reference#517) - Fix spelling (rust-lang/reference#520) - Update conditional-compilation.md (rust-lang/reference#503) - Document if_while_or_patterns (rust-lang/reference#516) - Fix some broken links. (rust-lang/reference#519) - Clarify what access struct updates do (rust-lang/reference#518) - Document irrefutable_let_patterns (rust-lang/reference#515) - Document Rc/Arc method receivers. (rust-lang/reference#494) - unions have no active field (rust-lang/reference#478) - attributes.md Outer -> Inner (rust-lang/reference#510) - Let bindings are now available in const contexts (rust-lang/reference#512) - Add missed literal at MacroFragSpec (rust-lang/reference#513) ## book 2 commits in fab9419503f0e34c1a06f9350a6705d0ce741dc6..9cffbeabec3bcec42d09432bfe7705125c848889 2019-02-25 07:53:23 -0500 to 2019-03-02 08:22:41 -0500 - More edits (rust-lang/book#1838) - Remove the 2018 edition nostarch directory ## edition-guide 1 commits in 5f3cc2a5618700efcde3bc00799744f21fa9ad2e..aa0022c875907886cae8f3ef8e9ebf6e2a5e728d 2019-02-27 20:11:50 -0800 to 2019-02-27 22:10:39 -0800 - Fix one last link in readme. (rust-lang/edition-guide#153) ## embedded-book 12 commits in bd2778f304989ee52be8201504d6ec621dd60ca9..9e656ead82bfe869493dec82653a52e27fa6a05c 2019-02-10 12:37:14 +0000 to 2019-03-03 16:03:26 +0000 - Merge rust-embedded/book#174 - Merge rust-embedded/book#172 - Merge rust-embedded/book#169 - Merge rust-embedded/book#171 - Merge rust-embedded/book#168 - Merge rust-embedded/book#153 - Merge rust-embedded/book#142 rust-embedded/book#151 - Merge rust-embedded/book#133 rust-embedded/book#135 - Merge rust-embedded/book#150 - Merge rust-embedded/book#145 - Merge rust-embedded/book#129 - Merge rust-embedded/book#128

petrochenkov reviewed Mar 1, 2019

View reviewed changes

Centril reviewed Mar 2, 2019

View reviewed changes

src/conditional-compilation.md Outdated Show resolved Hide resolved

src/procedural-macros.md Outdated Show resolved Hide resolved

Centril assigned petrochenkov Mar 2, 2019

Havvy reviewed Mar 2, 2019

View reviewed changes

src/attributes.md Show resolved Hide resolved

ehuss mentioned this pull request Mar 2, 2019

Remove "mode" from derive macro terminology. #530

Merged

petrochenkov approved these changes Mar 3, 2019

View reviewed changes

ehuss and others added 3 commits March 4, 2019 13:35

Update attribute documentation.

d847bde

Update for review comments.

884b952

Fix missing word typo.

609d740

Co-Authored-By: ehuss <[email protected]>

ehuss force-pushed the attribute-update branch from c05d0dd to 609d740 Compare March 4, 2019 21:35

Centril approved these changes Mar 5, 2019

View reviewed changes

Centril merged commit ce592df into rust-lang:master Mar 5, 2019

ehuss mentioned this pull request Mar 5, 2019

Update books rust-lang/rust#58936

Closed

ehuss mentioned this pull request Apr 21, 2019

Fix/clarify inert/active attributes, and attribute sequence. #565

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update attribute documentation. #528

Update attribute documentation. #528

ehuss commented Mar 1, 2019

ehuss commented Mar 1, 2019

petrochenkov Mar 1, 2019

ehuss Mar 1, 2019

petrochenkov Mar 1, 2019

ehuss Mar 1, 2019

petrochenkov Mar 1, 2019

ehuss Mar 1, 2019

petrochenkov commented Mar 1, 2019

ehuss commented Mar 1, 2019 •

edited

Loading

Centril left a comment

Havvy left a comment

petrochenkov commented Mar 2, 2019 •

edited

Loading

petrochenkov commented Mar 2, 2019

Centril commented Mar 2, 2019

ehuss commented Mar 2, 2019

Update attribute documentation. #528

Update attribute documentation. #528

Conversation

ehuss commented Mar 1, 2019

ehuss commented Mar 1, 2019

petrochenkov Mar 1, 2019

Choose a reason for hiding this comment

ehuss Mar 1, 2019

Choose a reason for hiding this comment

petrochenkov Mar 1, 2019

Choose a reason for hiding this comment

ehuss Mar 1, 2019

Choose a reason for hiding this comment

petrochenkov Mar 1, 2019

Choose a reason for hiding this comment

ehuss Mar 1, 2019

Choose a reason for hiding this comment

petrochenkov commented Mar 1, 2019

ehuss commented Mar 1, 2019 • edited Loading

Centril left a comment

Choose a reason for hiding this comment

Havvy left a comment

Choose a reason for hiding this comment

petrochenkov commented Mar 2, 2019 • edited Loading

petrochenkov commented Mar 2, 2019

Centril commented Mar 2, 2019

ehuss commented Mar 2, 2019

ehuss commented Mar 1, 2019 •

edited

Loading

petrochenkov commented Mar 2, 2019 •

edited

Loading