opened
carols10cents
username_0
Moving here from https://github.com/rust-lang/cargo/issues/4406 on @username_5's behalf:

While documenting every public function of [ThreadPool](https://github.com/rust-threadpool/rust-threadpool) I had to implement `#[derive(Clone)` manually so I would be able to add an example.

I assume `cargo doc` has a default template for the derive-able traits.
So I propose something like this:
```rust
#[derive(Clone)
/// My custom doc
/// ```
/// let my = custom.example();
/// ```
#[derive(PartialEq, Eq)
/// My custom doc for both traits
/// ```
/// let my = custom.example();
/// ```
struct CustomStruct;
```

The template would have to include something like "yield" within the code it is generating.
In this case it should generate something equal to:
```rust
impl Clone for CustomStruct {
    /// My custom doc
    /// ```
    /// let my = custom.example();
    /// ```
    fn clone(&self) -> Self { CustomStruct }
}
/* similar for the other two traits */
struct CustomStruct;
```

What do you think?
Document traits from #[derive(...)]
issue
created
sfackler
username_1
I think this'd make more sense if Rustdoc rendered impl-level documentation - There are two methods in `PartialEq`, and none in `Eq`, so it's not totally clear where the docs would go. Even Clone has `clone` and `clone_from`.
comment
created
durka
username_2
Nit: `///` doc comments are normally before the item they document.

Furthermore, I think this would need a slightly more complex syntax. Currently,

```rust
/// doc 1
#[attr]
/// doc 2
item {}
```

is the same as

```rust
/// doc 1
/// doc 2
#[attr]
item {}
```

(this is because `/// doc` just means `#[doc="doc"]`) so suddenly assigning extra meaning to the order of attributes seems weird IMO.

Something like `#[derive(Clone(doc="..."))]` or `#[derive(Clone)] #[clone(doc="...")]` could work, though then you have to stuff everything into a single string, which is annoying.
comment
created
steveklabnik
username_3
I am thinking a change of this magnitude requires an RFC, though I'm not sure.
comment
created
ollie27
username_4
rust-lang/rfcs#1382 could cover this.
comment
created
dns2utf8
username_5
One point that is important to me is, the docs should stay in the same file and near the `#[derive(X)]´
comment