Skip to content

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

Open
@llogiq

Description

@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

Metadata

Metadata

Assignees

No one assigned

    Labels

    C-feature-requestCategory: A feature request, i.e: not implemented / a PR.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.needs-rfcThis change is large or controversial enough that it should have an RFC accepted before doing it.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions