Document inert vs active attributes

src/SUMMARY.md

@@ -77,6 +77,7 @@
     - [Lexing and Parsing](./the-parser.md)
     - [Macro expansion](./macro-expansion.md)
     - [Name resolution](./name-resolution.md)
+    - [Attributes](./attributes.md)
     - [`#[test]` Implementation](./test-implementation.md)
     - [Panic Implementation](./panic-implementation.md)
     - [AST Validation](./ast-validation.md)

src/attributes.md

@@ -0,0 +1,49 @@
+# Attributes
+
+Attributes come in two types - 'builtin'/'inert' attributes, and 'non-builtin'/'active' attributes:
+
+## 'Builtin'/'inert' attributes
+
+These attributes are defined in the compiler itself, in
+[`compiler/rustc_feature/src/builtin_attrs.rs`][builtin_attrs]
+
+Example include `#[allow]` and `#[macro_use]`
+
+[builtin_attrs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_feature/builtin_attrs/index.html
+
+These attributes have several important characteristics:
+* They are always in scope, and do not participate in typical path-based resolution.
+* They cannot be renamed. For example, `use allow as foo` will compile, but writing `#[foo]` will
+  produce an error.
+* They are 'inert', meaning they are left as-is by the macro expansion code.
+  As a result, any behavior comes as a result of the compiler explicitly checking for their presence
+  (for example, lint-related code explicitly checks for `#[allow]`, `#[warn]`, `#[deny]`, and
+`#[forbid]`)
+
+## 'Non-builtin'/'active' attributes
+
+These attributes are defined by a crate - either the standard library, or a proc-macro crate.
+**Important**: Many non-builtin attributes, such as `#[derive]`, are still considered part of the
+core Rust language. However, they are **not** called 'builtin attributes', since they have a
+corresponding definition in the standard library.
+
+Definitions of non-builtin attributes take two forms:
+
+1. Proc-macro attributes, defined via a function annotated with `#[proc_macro_attribute]` in a
+   proc-macro crate.
+2. Ast-based attributes, defined in the standard library. These attributes have special 'stub'
+   macros defined in places like [`library/core/src/macros/mod.rs`][core_macros]
+
+[core_macros]:  https://github.com/rust-lang/rust/blob/master/library/core/src/macros/mod.rs
+
+These definitions exist to allow the macros to participate in typical path-based resolution - they
+can be imported, re-exported, and renamed just like any other item definition. However, the body of
+the definition is empty. Instead, the macro is annotated with the `#[rustc_builtin_macro]`
+attribute, which tells the compiler to run a corresponding function in `rustc_builtin_macros`.
+
+All non-builtin attributes have the following characteristics:
+* Like all other definitions (e.g. structs), they must be brought into scope via an import.
+  Many standard library attributes are included in the prelude - this is why writing `#[derive]`
+  works without an import.
+* They participate in macro expansion. The implementation of the macro may leave the attribute
+  target unchanged, modify the target, produce new AST nodes, or remove the target entirely.

src/test-implementation.md

@@ -2,7 +2,7 @@
 
 <!-- toc -->
 
-Today, rust programmers rely on a built in attribute called `#[test]`. All
+Today, rust programmers rely on an attribute called `#[test]`. All
 you have to do is mark a function as a test and include some asserts like so:
 
 ```rust,ignore