Update attribute documentation.

[ehuss]

• 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]

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]

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

[ehuss]

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

[petrochenkov]

"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.

[ehuss]

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]

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.

[ehuss]

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]

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]

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.

[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.

[petrochenkov]

@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]

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

[Centril]

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

[ehuss]

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.