Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove "mode" from derive macro terminology. #530

Merged
merged 1 commit into from
Mar 3, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions src/attributes.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ There are three kinds of attributes:

* Built-in attributes
* Macro attributes
* Derive mode helper attributes
* Derive macro helper attributes

## Active and inert attributes

Expand Down Expand Up @@ -184,7 +184,7 @@ which can be used to control type layout.

- `proc_macro` - Defines a [function-like macro].

- `proc_macro_derive` - Defines a [derive mode macro].
- `proc_macro_derive` - Defines a [derive macro].

- `proc_macro_attribute` - Defines an [attribute macro].

Expand Down Expand Up @@ -587,7 +587,7 @@ You can implement `derive` for your own traits through [procedural macros].
[attribute macro]: procedural-macros.html#attribute-macros
[function-like macro]: procedural-macros.html#function-like-procedural-macros
[conditional compilation]: conditional-compilation.html
[derive mode macro]: procedural-macros.html#derive-mode-macros
[derive macro]: procedural-macros.html#derive-macros
[trait]: items/traits.html
[main]: crates-and-source-files.html
[`Termination`]: ../std/process/trait.Termination.html
Expand Down
32 changes: 16 additions & 16 deletions src/procedural-macros.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
Procedural macros come in one of three flavors:

* [Function-like macros] - `custom!(...)`
* [Derive mode macros] - `#[derive(CustomMode)]`
* [Derive macros] - `#[derive(CustomDerive)]`
* [Attribute macros] - `#[CustomAttribute]`

Procedural macros allow you to run code at compile time that operates over Rust
Expand Down Expand Up @@ -111,21 +111,21 @@ with curly braces and no semicolon or a different delimiter followed by a
semicolon. For example, `make_answer` from the previous example can be invoked
as `make_answer!{}`, `make_answer!();` or `make_answer![];`.

### Derive mode macros
### Derive macros

*Derive mode macros* define new modes for the `derive` [attribute]. These macros
define new [items] given the token stream of a [struct], [enum], or [union].
They also define [derive mode helper attributes].
*Derive macros* define new inputs for the `derive` [attribute]. These macros
can create new [items] given the token stream of a [struct], [enum], or [union].
They can also define [derive macro helper attributes].

Custom deriver modes are defined by a [public] [function] with the
Custom derive macros are defined by a [public] [function] with the
`proc_macro_derive` attribute and a signature of `(TokenStream) -> TokenStream`.

The input [`TokenStream`] is the token stream of the item that has the `derive`
attribute on it. The output [`TokenStream`] must be a set of items that are
then appended to the [module] or [block] that the item from the input
[`TokenStream`] is in.

The following is an example of a derive mode macro. Instead of doing anything
The following is an example of a derive macro. Instead of doing anything
useful with its input, it just appends a function `answer`.

```rust,ignore
Expand All @@ -138,7 +138,7 @@ pub fn derive_answer_fn(_item: TokenStream) -> TokenStream {
}
```

And then using said derive mode:
And then using said derive macro:

```rust,ignore
extern crate proc_macro_examples;
Expand All @@ -152,18 +152,18 @@ fn main() {
}
```

#### Derive mode helper attributes
#### Derive macro helper attributes

Derive mode macros can add additional [attributes] into the scope of the [item]
they are on. Said attributes are called *derive mode helper attributes*. These
Derive macros can add additional [attributes] into the scope of the [item]
they are on. Said attributes are called *derive macro helper attributes*. These
attributes are [inert], and their only purpose is to be fed into the derive
mode macro that defined them. That said, they can be seen by all macros.
macro that defined them. That said, they can be seen by all macros.

The way to define helper attributes is to put an `attributes` key in the
`proc_macro_derive` macro with a comma separated list of identifiers that are
the names of the helper attributes.

For example, the following derive mode macro defines a helper attribute
For example, the following derive macro defines a helper attribute
`helper`, but ultimately doesn't do anything with it.

```rust,ignore
Expand All @@ -177,7 +177,7 @@ pub fn derive_helper_attr(_item: TokenStream) -> TokenStream {
}
```

And then usage on the derive mode on a struct:
And then usage on the derive macro on a struct:

```rust,ignore
# #![crate_type="proc-macro"]
Expand Down Expand Up @@ -272,15 +272,15 @@ fn invoke4() {}
[`derive`]: attributes.html#derive
[`proc_macro` crate]: ../proc_macro/index.html
[Cargo's build scripts]: ../cargo/reference/build-scripts.html
[Derive mode macros]: #derive-mode-macros
[Derive macros]: #derive-macros
[Attribute macros]: #attribute-macros
[Function-like macros]: #function-like-procedural-macros
[attribute]: attributes.html
[attributes]: attributes.html
[block]: expressions/block-expr.html
[custom attributes]: attributes.html
[crate type]: linkage.html
[derive mode helper attributes]: #derive-mode-helper-attributes
[derive macro helper attributes]: #derive-macro-helper-attributes
[enum]: items/enumerations.html
[inert]: attributes.html#active-and-inert-attributes
[item]: items.html
Expand Down