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

[ehuss]

The inert/active attribute description is not be correct. The following comment needs to be incorporated: https://github.com/rust-lang-nursery/reference/pull/537#pullrequestreview-218090880

However, I think the inert/active distinction is subtle and should have more clarification. It is possible to "see" an active attribute based on the point in time during compilation (for example, an attribute macro placed before #[test] sees the test attribute, it has not been removed, yet).

Also, to me it seems like like cfg and cfg_attr aren't always active. If the predicate is true, they are clearly visible from attribute macros, so they have not been removed. This comment implies that things are broken.

I would like to know how I can validate this inert/active distinction by reading the rustc code. It is not tracked in any data structure I can see, and I do not know through which mechanism an attribute removes itself. Otherwise I feel like I am shooting in the dark trying to document this.

Also I think the order that attributes are processed and when attributes remove themselves should be documented. For example, do attribute macros see derive macros (yes, the derive has not been removed, yet). What is the significance of the order that attributes are listed? (Presumably they are processed top-down?) Attribute macros seem to be removed only after they are processed (an attribute macro sees the attributes below it, but not above it). When is cfg pruning done (pretty early)? In general I think the order attributes are processed and when attributes remove themselves should be documented.

[petrochenkov]

I would like to know how I can validate this inert/active distinction by reading the rustc code.

If the attribute resolves to Def::Macro, then it's active. If the attribute resolves to Def::NonMacroAttr, then it's inert. Built-in attributes bypass resolution (kind of, only the initial pass, but not the validation pass) and they are all inert, unless they are explicitly expanded by special code in libsyntax like cfg, cfg_attr and derive.

I do not know through which mechanism an attribute removes itself.

Through generic macro expansion machinery usually. Through hacks for cfg, cfg_attr and derive.

Also I think the order that attributes are processed and when attributes remove themselves should be documented.

The general intent is to expand everything in straightforward left-to-right fashion (except for cfg/cfg_attr):

#[my_attr]
#[derive(MyDerive)]
#[my_attr2]
ITEM
=>

my_attr!(MyDerive!(my_attr2!(ITEM)))

basically.

Derives currently have some issues in this area due to their chaotic Macro 1.1 and legacy nature, but they should be realistically fixable without noticeable breakage.

[petrochenkov]

After https://github.com/rust-lang/rust/pull/79078 derive is a regular proc macro attribute without any special properties with regards to expansion order.