Six forms of doc comments are five too many

[bstrie]

Currently we have six forms of doc comments:

• outer line ///
• outer block /** */
• inner line //!
• inner block /*! */
• outer attribute #[doc=""]
• inner attribute #[doc="";]

Ideally this would be reduced to one, but if two are necessary then that's fine. It's perfectly acceptable to not cater to every miniscule style convention. Here is my proposal:

1. Remove the direct attribute forms, since their unwieldiness was why we introduced the comment syntax in the first place. This reduces to four.
2. Select either line or block, and remove the other. This reduces to two.
3. Remove the inner form if possible. If we can find some special way to document modules without requiring a special syntax just for that, then so much the better.

Alternatively, we could conclude that it's simply too much trouble to have special forms for doc comments and just stick with the attribute forms. This would be somewhat uglier, but more consistent with the rest of the language

[Kimundi]

I'd say remove the block ones, only allow the inner line ones for modules, only allow the outer line ones for everything else, remove/lint-off the attribute ones.

[Aatch]

@Kimundi if we are to remove a form, I'd prefer removing the line form. Most of the issues relating to doc comments are only applicable to the line form because ultimately, they aren't suited to formatting a block of text.

Also, the block form is more consistent with other languages.

[Dretch]

In order to avoid making only one kind of comment special, I suggest not having any comments be special, and instead having something like:

### Documentation blocks look like this...
### ... completely different to comments ...
### ... but prettier than #[doc = "..."]

Module comments could be denoted by starting them with four hashes instead of three.

[cscott]

@Aatch +1. Inner block/outer block seems sufficient to me.

@Dretch's proposal seems likely to lead to eight forms of doc comments, in practice.

[ben0x539]

Aw, I liked line comments.

Maybe mod self; could be valid syntax so that we can put non-inner doc comments over it. :)

[emberian]

I don't consider the attribute a doc comment since it isn't a comment. I don't think this is really a big issue at all, but I wouldn't mind seeing line comments gone.

[Kimundi]

After some discussion on irc today, I'd like to make an alternative proposal: Don't remove any of the existing forms, but instead

• Make consecutive /// and //! comments without an empty line between them count as one doc attribute with multiple lines of text.
• Limit the amount of doc attributes per item to exactly one.
• Decide on a fixed, lint-backed convention for the rust source itself: A //! block for inside an module and a /// block everywhere else seems to be where we're going right now.

This would at least solve the ambiguity problems.

[emberian]

@Kimundi we already do #1 in that list. #2 should be refined to "only one name-value pair for doc", so we can still have #[doc(hidden)] /// foo

[Kimundi]

@cmr: Ah right, that's technical still a doc attribute, isn't it. ;)

But yeah, one name-value pair only.

[metajack]

Triage bump.

I haven't seen any uses of /** */ style in Servo, and certainly not any #[doc="..."].

[rust-highfive]

This issue has been moved to the RFCs repo: rust-lang/rfcs#287