rustdoc: split out trait implementer's notes from method docs

[llogiq]

On mastodon, Simon Tatham alerted us to the problem that rustdoc will show the method docs from a trait on an implementation of that trait, which may contain parts geared towards implementers, not users of the trait.

There is currently no way to distinguish those in a way that would let rustdoc show the implementer's notes on the trait docs but not on trait implementations.

Since doc comments get lowered to attributes, the lowest common. denominator would be an attribute like #[traitdoc = "..."] that works like #[doc = "..."] but is included by rustdoc only on the doc pages for the trait itself, not on the implementation docs.

In addition, there could be a doc comment variant (perhaps ///^ and //!^ respectively) that lowers to #[traitdoc] attributes. This might need an edition though. Alternatively, rust could pick up on an ## Implementer's notes section header instead and emit #[traitdoc] instead of #[doc] attributes for that whole section.

Example

As an example, the PartialEq::ne method could be documented as follows (other methods and attributes have been removed for brevity):

pub trait PartialEq<Rhs: ?Sized = Self> {
    /// Tests for `self != other`.
    #[traitdoc="The default implementation is almost always sufficient,"]
    #[traitdoc="and should not be overridden without very good reason."]
    fn ne(&self, other: &Rhs) -> bool {
        !self.eq(other)
    }
}

Open questions:

• Attribute naming: Some alternatives are impldoc, trait_doc, trait-doc, impl-doc.
• Section header or doc comment variant? If the latter, which sigil to append?

cc @GuillaumeGomez

[GuillaumeGomez]

Here is the solution I have in mind:

/// Docs visible by everyone.
#[doc(visible_on_trait_only = true)]
/// This is how to implement the trait.
/// blablabla
#[doc(visible_on_trait_only = false)]
/// eventually more docs

We could add a new doc attribute which would make the documentation between these attributes only visible on the trait page and not on the implementors. The #[doc(visible_on_trait_only = false)] one would be optional if there is no doc afterward.

What do you think?

[GuillaumeGomez]

Also cc @sgtatham.

[llogiq]

@GuillaumeGomez looks good as a starting point. With that said, such a toggle attribute might complicate parsing and conversion in case we decide to go ahead with a comment prefix shortcut later. Remember, this would also be for library authors to document their traits.

[GuillaumeGomez]

I don't think there will ever be more syntax sugar ever added for doc comments (if that's what you meant).

And do you mean parsing/conversion for humans or for rustdoc?