Document traits from #[derive(...)]

[carols10cents]

Moving here from rust-lang/cargo#4406 on @dns2utf8's behalf:

While documenting every public function of 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:

#[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:

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?

[sfackler]

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.

[durka]

Nit: /// doc comments are normally before the item they document.

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

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

is the same as

/// 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.

[steveklabnik]

I am thinking a change of this magnitude requires an RFC, though I'm not sure.

[ollie27]

rust-lang/rfcs#1382 could cover this.

[dns2utf8]

One point that is important to me is, the docs should stay in the same file and near the `#[derive(X)]´