Attribute template

Attributes should use the following template. Examples are given for phrasing you should use, but you should deviate if the attribute doesn't fit any of the examples or if they get in the way of clarity.

When an attribute (or a new attribute position in the grammar) is added, be sure to update all the “attributes on” sections which list which attributes can be used in various positions.

r[PARENT.example]

The `example` attribute

r[PARENT.example.intro] The example [attribute][attributes] ...give a high level description.

[!EXAMPLE]

// This should be a very basic example showing the attribute
// used in some way.
#[example]
fn some_meaningful_name() {}

r[PARENT.example.syntax] Describe the accepted syntax of this attribute. You can either explain that it uses one of the pre-existing grammars like MetaWord or define an explicit grammar. If there are different forms, briefly describe the syntax here, and link to the appropriate rules below that explain the behavior of the different forms. Examples:

The example attribute uses the [MetaWord] syntax.

The example attribute uses the [MetaListPaths] syntax to specify a list of ...

The example attribute uses the [MetaWord] and [MetaNameValueStr] syntaxes.

The example attribute uses the [MetaWord], [MetaListPaths], and [MetaNameValueStr] syntaxes.

The example attribute uses the [MetaNameValueStr] syntax. Accepted values are "X" and "Y".

The example attribute uses the [MetaNameValueStr] syntax. The value in the string must be ...

The example attribute has these forms:

[MetaWord]
[!EXAMPLE]
```
#[example]
fn f() {}
```
[MetaNameValueStr] --- The given string must ...
[!EXAMPLE]
```
#[example = "example"]
fn f() {}
```
[MetaListNameValueStr] --- As with the [MetaNameValueStr] syntax, the given string must ...
[!EXAMPLE]
```
#[example(inner = "example")]
fn f() {}
```

The syntax for the example attribute is:

@root ExampleAttribute -> `example` `(` ... `)`

r[PARENT.example.syntax.foo] The [MetaNameValueStr] form of the example attribute provides a way to specify the foo.

[!EXAMPLE]

#[example = "example"]
fn some_meaningful_name() {}

r[PARENT.example.allowed-positions] Explain the valid positions where this attribute may be used.

See check_attr and builtin_attrs.rs in the compiler. Don't forget that some attributes only work as inner or outer attributes. Examples:

The example attribute may only be applied to ...

The example attribute may only be applied to the crate root.

The example attribute is allowed anywhere attributes are allowed.

If there are unused attribute warnings, or if rustc is incorrectly accepting some positions, include a note about these.

[!NOTE] rustc ignores use in other positions but lints against it. This may become an error in the future.

r[PARENT.example.duplicates] Explain the behavior if the attribute is specified multiple times on an element. See AttributeDuplicates in the compiler. Examples:

The example attribute may be used any number of times on a form.

Using example more than once on a form has the same effect as using it once.

The example attribute may be used only once on ...

Only the first use of example on an item has effect.

[!NOTE] rustc lints against any use following the first. This may become an error in the future.

[!NOTE] rustc lints against any use following the first with a future-compatibility warning. This may become an error in the future.

Only the last use of example on an item has effect.

[!NOTE] rustc lints against any use preceding the last. This may become an error in the future.

Only the last use of example on an item is used to ...

If the example attribute is used more than once on an item, then the combination of all the specified values is used as ...explain how they are merged.

r[PARENT.example.ATTR_NAME] If this attribute cannot be used with another attribute, specify each one. Do this on both attributes. Example:

The example attribute may not be used with the [foo] attribute.

r[PARENT.example.unsafe] If this is an unsafe attribute, explain the safety conditions it must uphold. If not, don't include this section. Be sure to also update attributes.safety when adding a new unsafe attribute. Example:

The example attribute must be marked with [unsafe][attributes.safety] because ...

r[PARENT.example.stdlib] This rule explains if the attribute is exported in the standard library. Skip this if it is not. Example:

The example attribute is exported in the standard library prelude as [core::prelude::v1::example].

r[PARENT.example.foo] From here on, add rules explaining all the behaviors of the attribute. If the attribute is very simple, you can just have one rule called “.behavior” to explain its behavior. More complex attributes, such as those with multiple kinds of inputs or different modes should describe each as a separate rule.

Attribute template

The example attribute

The `example` attribute