diff --git a/src/attributes/derive.md b/src/attributes/derive.md index 18ba01ed33..c38bf19c7a 100644 --- a/src/attributes/derive.md +++ b/src/attributes/derive.md @@ -2,38 +2,66 @@ r[attributes.derive] # Derive r[attributes.derive.intro] -The *`derive` attribute* allows new [items] to be automatically generated for -data structures. +The *`derive` [attribute][attributes]* invokes one or more [derive macros], allowing new [items] to be automatically generated for data structures. You can create `derive` macros with [procedural macros]. + +> [!EXAMPLE] +> The [`PartialEq`][macro@PartialEq] derive macro emits an [implementation] of [`PartialEq`] for `Foo where T: PartialEq`. The [`Clone`][macro@Clone] derive macro does likewise for [`Clone`]. +> +> ```rust +> #[derive(PartialEq, Clone)] +> struct Foo { +> a: i32, +> b: T, +> } +> ``` +> +> The generated `impl` items are equivalent to: +> +> ```rust +> # struct Foo { a: i32, b: T } +> impl PartialEq for Foo { +> fn eq(&self, other: &Foo) -> bool { +> self.a == other.a && self.b == other.b +> } +> } +> +> impl Clone for Foo { +> fn clone(&self) -> Self { +> Foo { a: self.a.clone(), b: self.b.clone() } +> } +> } +> ``` r[attributes.derive.syntax] -It uses the [MetaListPaths] syntax to specify a list of -traits to implement or paths to [derive macros] to process. - -For example, the following will create an [`impl` item] for the -[`PartialEq`] and [`Clone`] traits for `Foo`, and the type parameter `T` will be -given the `PartialEq` or `Clone` constraints for the appropriate `impl`: - -```rust -#[derive(PartialEq, Clone)] -struct Foo { - a: i32, - b: T, -} -``` - -The generated `impl` for `PartialEq` is equivalent to - -```rust -# struct Foo { a: i32, b: T } -impl PartialEq for Foo { - fn eq(&self, other: &Foo) -> bool { - self.a == other.a && self.b == other.b - } -} -``` - -r[attributes.derive.proc-macro] -You can implement `derive` for your own traits through [procedural macros]. +The `derive` attribute uses the [MetaListPaths] syntax to specify a list of paths to [derive macros] to invoke. + +r[attributes.derive.allowed-positions] +The `derive` attribute may be applied to [structs][items.struct], [enums][items.enum], and [unions][items.union]. + +r[attributes.derive.duplicates] +The `derive` attribute may be specified multiple times on an item, with all derive macros listed in all attributes being invoked. + +r[attributes.derive.stdlib] +The `derive` attribute is exported in the standard library prelude as [`core::prelude::v1::derive`]. + +r[attributes.derive.built-in] +Built-in derives are defined in the [language prelude][names.preludes.lang]. The list of built-in derives are: + +- [`Clone`] +- [`Copy`] +- [`Debug`] +- [`Default`] +- [`Eq`] +- [`Hash`] +- [`Ord`] +- [`PartialEq`] +- [`PartialOrd`] + +r[attributes.derive.built-in-automatically_derived] +The built-in derives include the [`automatically_derived` attribute][attributes.derive.automatically_derived] on the implementations they generate. + +r[attributes.derive.behavior] +During macro expansion, for each element in the list of derives, the corresponding derive macro expands to zero or more [items]. r[attributes.derive.automatically_derived] ## The `automatically_derived` attribute @@ -43,7 +71,6 @@ The *`automatically_derived` attribute* is automatically added to has no direct effect, but it may be used by tools and diagnostic lints to detect these automatically generated implementations. -[`impl` item]: ../items/implementations.md [items]: ../items.md [derive macros]: ../procedural-macros.md#derive-macros [implementations]: ../items/implementations.md diff --git a/src/names/preludes.md b/src/names/preludes.md index 97edc59fc3..97c1ba77df 100644 --- a/src/names/preludes.md +++ b/src/names/preludes.md @@ -124,6 +124,7 @@ It includes the following: * [floating-point types] --- `f32` and `f64` * [Macro namespace] * [Built-in attributes] + * [Built-in derive macros][attributes.derive.built-in] r[names.preludes.macro_use] ## `macro_use` prelude