Unify doc comment style?

[alxgnon]

The majority of the Rust codebase uses /// style doc comments. Rarely will a file contain occurences of /**. I think it is safe to say that the /// style is currently preferred. I would like to see the entire codebase subscribe to a single doc comment style.

This is a quite trivial fix for existing code, but I'd like to hear some external opinion before I make the change (or don't, depending).

[steveklabnik]

Yup. /// is preferred, though I understand //! Is still used for top level documentation for modules for some reason.

[alxgnon]

Yeah, getting rid of inconsistent inner docs would be another desirable step to unifying doc comment style.

[huonw]

Putting module docs on the mod declaration (which is in a separate file) would be a step backwards IMO: it seems better to keep the docs close to the thing they are documenting.

[thehydroimpulse]

I like the current situation where:

• /// is used for top-level items. (structs, enums, functions, etc...)
• // is used within functions, for example. To document procedures, etc...
• //! for top-level documentation (modules, crates)

It also allows syntax highlighters to have different schemes to differentiate the different types of comments.

[alxgnon]

@thehydroimpulse That is the style that the Rust codebase seems to prefer. What I want to remove is block documentation comments (/**, /*!).
@huonw Of course, that is the useful case for inner doc comments, and it seems to be the preferred way to document modules. Inconsistent use of inner docs would be on functions and types for example.

[thehydroimpulse]

@alxgnon Then I agree we should get rid of /** and /*! (originally, I thought you meant to only have /// and get rid of // and //!)

[huonw]

/*!//** are useful for large doc comments, where prefixing every line with // would be horrible, e.g. borrowck::doc is 1000+ lines of documentation. (Although maybe the best fix for this is #15470.)

// is used within functions, for example. To document procedures, etc...

I can't tell from your comment if you're thinking this is a convention or not, but... /// and //! are actually deeply understood by the compiler, they're just sugar for #[doc = "..."] attributes (meaning it's nonsensical and illegal to put them just anywhere inside functions). The // comments just ignored like normal comments from other languages.

[steveklabnik]

We have issues here as well as an open RFC for doc coments, so I'm gonna give this one a close.