Six forms of doc comments are five too many

[rust-highfive]

Issue by bstrie
Tuesday May 28, 2013 at 12:36 GMT

For earlier discussion, see rust-lang/rust#6782

This issue was labelled with: B-RFC in the Rust repository

---

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

[quantheory]

My personal opinion (acknowledging that probably none of these will happen until Rust 2.0, if ever):

1. I totally agree with this. Once you have the doc comments as the standard, the attributes are pretty silly.
2. I almost totally disagree with this. If both line and block comments exist, there should be doc comment versions of both. However, "outer line" adds an extra slash, while "outer block" adds an extra asterisk. This is strange to me, because it doesn't fit with the "add one more specific character" style of inner blocks. If this one discrepancy was resolved, I would argue that this doesn't even count as another "form of doc comment" at all, because the line vs. block question would be completely orthogonal to whether something was a normal vs. doc comment.
3. I disagree completely, mostly because I think that this is impossible without adding more complexity (both in software and for humans). For crates and most modules some inner form must exist. For everything else (possibly including those rare "inline" modules defined in the same file as a parent crate/module) most people prefer the outer form, which I can think of some good reasons for. I think it's better to allow both forms everywhere (and let projects have their own style guides) than to pick and choose which form works for which items. Especially since that's already implemented and apparently works fine.

[sfackler]

The attribute forms are useful since they can be passed through macros: https://github.com/sfackler/rust-postgres/blob/master/src/types/mod.rs#L244

[nixpulvis]

I think the distinction makes perfect sense, and each has a good use case. And despite being 6 forms, there are really only 3x2 with some consistencies. For example inner vs outer is always is a matter of a !.

[pradyunsg]

Please close this issue as it will be superseded by the discussion at #1371.

[nrc]

closing - dup of #1371