---
# System prepended metadata

title: Attribute template

---

Attribute template

r[PARENT.example]
## The `example` attribute

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

> [!EXAMPLE]
> ```rust
> // 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.
Usually this is just explaining it is one the `Meta*` grammars, and the particular inputs it accepts. 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. If the attribute takes a non-standard "meta" syntax, define a `grammar` block with the allowed syntax. Example:

The `example` attribute uses the [MetaWord] syntax and thus does not take any inputs.


Include `[!EXAMPLE]` blocks if there are multiple forms showing the different forms.

r[PARENT.example.allowed-positions]
Explain the valid positions where this attribute can be used.
See [`check_attr`](https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_passes/src/check_attr.rs) and [`builtin_attrs.rs`](https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_feature/src/builtin_attrs.rs) in the compiler. Don't forget that some attributes only work as inner or outer attributes. Example:

The `example` attribute can be applied to ...
The `example` attribute can only be applied to the crate root.


r[PARENT.example.duplicates]
Explain the behavior if the attribute is specified multiple times on an element.
See [`AttributeDuplicates`](https://github.com/rust-lang/rust/blob/40d2563ea200f9327a8cb8b99a0fb82f75a7365c/compiler/rustc_feature/src/builtin_attrs.rs#L143) in the compiler. Example:

Duplicate instances of the `example` attribute have no effect.
Duplicate instances of the `example` attribute on the same ... have no effect.
It is an error to specify the `example` attribute multiple times on an item.
Only the first instance of `example` on an item is honored. Subsequent `example` attributes are ignored.
Only the last instance of `example` on an item is honored. Previous `example` attributes are ignored.

TODO

r[PARENT.example.ATTR_NAME]
If this attribute cannot be used with another attribute, specify each one.

The [`foo`] attribute cannot be used with the `example` attribute.

TODO: Should this be reflexive? That is, should it be on both sides?

r[PARENT.example.unsafe]
If this is an `unsafe` attribute, explain the safety conditions it must uphold. If not, don't include this section. Example:

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

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

*This rule should be skipped if it is not exported in the standard library.*

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.
