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

Moving here from https://github.com/rust-lang/cargo/issues/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?

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.

   Steven Fackler at 2017-08-28 01:45:34

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

   Alex Burka at 2017-08-28 03:15:43

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

   Steve Klabnik at 2017-08-28 06:23:28

4. rust-lang/rfcs#1382 could cover this.

   Oliver Middleton at 2017-08-28 16:04:44

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

   Stefan Schindler at 2017-09-12 16:16:27