Description
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?