# \[rustdoc\] docs for derived impls

**URL:** <https://internals.rust-lang.org/t/rustdoc-docs-for-derived-impls/22728>\
**Category:** tools and infrastructure\
**Created:** [April 10, 2025, 9:45pm UTC](https://internals.rust-lang.org/t/rustdoc-docs-for-derived-impls/22728 "2025-04-10T21:45:08Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![binarycat](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/binarycat/32/12210_2.png) [@binarycat](https://internals.rust-lang.org/u/binarycat)\
**Post date:** [April 10, 2025, 9:45pm UTC](https://internals.rust-lang.org/t/rustdoc-docs-for-derived-impls/22728/1 "2025-04-10T21:45:08Z")

</div>

It is possible to provide documentation on `impl` blocks, or on the methods in those blocks, except for when that block is created by a derive macro.

this may be desirable to document the nature of an impl, especially when customizing the impl with helper attributes such as `#[serde(skip)]`.

---

<div class="post-metadata">

**Author:** ![idanarye](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/idanarye/32/3346_2.png) [@idanarye](https://internals.rust-lang.org/u/idanarye)\
**Post date:** [April 10, 2025, 10:59pm UTC](https://internals.rust-lang.org/t/rustdoc-docs-for-derived-impls/22728/2 "2025-04-10T22:59:40Z")

</div>

This is something that needs to be implemented by each derive macro individually. A derive macro does not _have_ to create a single `impl` of the same name. It can create whatever code it wants - multiple `impl` blocks, new types, standalone functions, maybe even nothing at all (not useful, but possible). The only rules are that the derive macro cannot touch the type declaration itself - except for removing the attributes associated with it, which is done by the builtin attribute macro `#[derive]` rather by the individual derive macros.

This means there is nothing the language can do to add documentation on the `impl` block - the derive macro will have to do it. Which it can do today, via attributes:

```rust
/// Some documentation for the type itself
#[derive(Default)]
#[default(doc = "Some documentation for the Default impl")]
struct MyCollection(Vec<i32>);

```

There is one thing the language can do to help though. Just like it allows declaring associated attributes for the macro, it can allow declaring attributes for the doc comment:

```rust
/// Some documentation for the type itself
///
/// # #[default]
///
/// Some documentation for the Default impl
#[derive(Default)]
struct MyCollection(Vec<i32>);

```

The `derive` macro could strip any section of the doc comment tagged with an attribute associated with any of the derives. It'd still be up to the derive macros to parse the doc comment and emit their own doc comments on whatever they create.

---

<div class="post-metadata">

**Author:** ![kpreid](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/kpreid/32/8484_2.png) [@kpreid](https://internals.rust-lang.org/u/kpreid)\
**Post date:** [April 11, 2025, 4:17am UTC](https://internals.rust-lang.org/t/rustdoc-docs-for-derived-impls/22728/3 "2025-04-11T04:17:57Z")

</div>

> [@idanarye](#):
>
> The `derive` macro could strip any section of the doc comment tagged with an attribute associated with any of the derives. It'd still be up to the derive macros to parse the doc comment and emit their own doc comments on whatever they create.

I think it would be better to avoid adding more layers of _text_ processing, and I see a way to do it: you can already use doc comment syntax as part of the contents of an attribute; the following is syntactically valid:

```rust
#[derive(Foo)]
#[foo_doc(
    /// Hello world
)]
struct Bar {}

```

Derive macros could add support for documentation specified using helper attributes of this form without any changes to the language. (If this becomes a common pattern, rustfmt support for it would be useful, though; currently it is unformatted.)

---

<div class="post-metadata">

**Author:** ![binarycat](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/binarycat/32/12210_2.png) [@binarycat](https://internals.rust-lang.org/u/binarycat)\
**Post date:** [April 11, 2025, 6:35am UTC](https://internals.rust-lang.org/t/rustdoc-docs-for-derived-impls/22728/4 "2025-04-11T06:35:47Z")

</div>

```rust
#[serde(/** ignores the `foo` field */)]

```

this would be another option

---

<div class="post-metadata">

**Author:** ![system](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/system/32/14092_2.png) [@system](https://internals.rust-lang.org/u/system)\
**Post date:** [October 3, 2026, 6:35am UTC](https://internals.rust-lang.org/t/rustdoc-docs-for-derived-impls/22728/5 "2026-10-03T06:35:56Z")

</div>

Closed on October 3, 2026, 6:35am UTC

This topic was automatically closed 540 days after the last reply. New replies are no longer allowed.
