Deprecate some kinds of doc comments

[nrc]

With the intention of removing them in 2.0.

It is ridiculous how many kinds of comments we have, lets settle on one kind of doc comment and have done. We can make it really easy for people to migrate with tool support. Personally, I would like to keep only ///, but I don't really care as long as we just have one kind.

[nagisa]

I remember seeing a similar issue/RFC somewhere already. While I personally do not ever use block comments/doc-comments and would be fine removing them, I do not see how you would document crate without //!?

[alfiedotwtf]

Please don't remove /* */. It's convenient to quickly comment out code while debugging. Multi-line comments a good thing.

[gsingh93]

@alfiedotwtf Any decent editor can comment out multiple lines faster than you can type /* */

[alfiedotwtf]

@gsingh93 No. I can comment out code thousands of lines apart by bouncing in Vim without leaving my keyboard, which in reality only modifies two lines.

Also, why push features to a person's editor rather than the language itself. That's like saying we don't need Rust at all because we have Valgrind and cppcheck.

[gsingh93]

I can do the same thing in Emacs without leaving my keyboard, and I'm betting you can do it in Vim as well.

[brendanzab]

We are talking about doc comments here! I'm guessing @nrc is referring to the little-used /** */ and /*! */ doc comments. Those comments would still work - they just would no longer be recognised as documentation.

👍 from me (although I would like to see //! remain)

[Gankra]

🔥 💀 Death to /*! 💀 🔥

[steveklabnik]

I'm 👍 on removing all block comments. We do have a lot of comments, but It'd be weird to remove one kind of doc comments. The symmetry is nice.

[arielb1]

-100 for removing non-doc block comments. I don't care much about block doc comments.

[Manishearth]

👍 to this RfC. Nobody seems to use the block doc comments. We can land a deprecation lint for this syntax, too.

However, I feel we should keep the inner doc comments (//!) around.

IMO we should not remove regular block comments at all.

[BurntSushi]

I use block doc comments all the time for module/crate level documentation. I think it's a nice convenience. I'm not sure I'd argue strongly to keep them if I'm their sole benefactor though.

[frewsxcv]

👍 for removing block doc comments

[huonw]

Discussed previously: rust-lang/rust#6782 which was moved to #287.

[SimonSapin]

I’ve used /*! … */ in doc-comments that contain large code example. It’s really annoying to prefix every line with /// when writing code. (Auto-indenting the new line on doesn’t work, for example.)

[AngusP]

Block comments vs per-line has always been a hot topic, removing one in favour of the other would be generally unpopular. Maybe dropping either //! /*! */ or /// /** */ makes sense but you'd have to keep the option of block comments vs per-line prefix. Most self-respecting languages leave this style choice to the programmer.

Personally I don't think that the current system is particularly confusing, it's perhaps just overly verbose.

[Manishearth]

@AngusP note that this issue is primarily about documentation comments, not regular ones.

[AngusP]

@Manishearth though I'd argue that the same degree of choice should be available in doc comments as regular ones, both for ease of use and to encourage developers to write documentation comments.

[Gankra]

My opposition to block doc comments is primarily that the official style guide says not to use them... which basically makes them worthless? Normal block comments are good because they're tools for "make all this code go away for now", but docs are never temporary.

[withoutboats]

For deprecating doc blocks, against deprecating normal blocks, which I use inline while building stuff out all the time. Against removing //! because it makes documenting modules much more pleasant.

[AngusP]

I'm against removing one style (block vs line) of comments in preference to another; I'm also not really bothered by the existence of multiple types of doc comment.

[pradyunsg]

@nrc Please make OP more clear that this issue is only about documentation comments. People are getting confused.

[pradyunsg]

I disagree.

To me, it seems pretty nice how everything stands. Every comment style has a unique, non-replaceable purpose.

• Dropping either block or line (documentation) comments now would be pretty unpopular. If Rust never had block comments, it would have been much cleaner because then there would have been just 3 types of comments. It would have been more characters but simpler too. (And it's easier to add stuff than remove, at least in languages)
• Having outer and inner documentation comments allows for unambiguously deciphering what is being documented. 4 types of documentation comments felt a little silly to me initially. Soon, I realized having outer and inner doc-comments is in fact useful. Then, because there's 2 styles of comments, there's 2x2 doc-comments.
  • Removing either form will make it harder for people and tools to decipher what is being documented and it would be rude/not nice to remove either form as they both have documented recommended uses.

---

If anything will be dropped, please please keep the symmetry. Either drop all of one kind or don't. Having block comments but not block documentation comments will be pretty odd.

---

RFC-505 has a statement:

Avoid block comments.

Block (documentation) comments are useful as they reduces visual noise in large amounts of text by removing the need for a comment token on every line. While they are recommended against, IMO they are still pretty useful.

Single line (documentation) comments are useful as they add information to every line, marking the line explicitly as a comment. They are also more convenient for short pieces of text.

---

Off-Shoot Idea: How about some syntactic sugar for #[doc="..."] to make life simpler? Then we could simply drop all kinds of documentation comments and use attributes directly. Just a thought.

Edit: Am I missing something? Does this idea even make sense? I should sleep.

[CAD97]

@pradyunsg doc comments are the sugar for #[doc="..."]. You can observe this in-language with macro_rules, as doc comments are matched via $(#[$:meta])*.

(Yes, I realize this is a reply over a year later. Just wanted to clarify this.)

(Edited to add: wow, this was added seconds before the next comment)

[ssokolow]

Despite my 15+ years working in Python and, prior to that QBasic, Visual Basic, and DOS batch files, I've never liked single-line comment syntax for multi-line comments... especially for structured documentation which relies on it for things like preformatted code snippets and Markdown list syntax and.

It feels like needless noise which significantly and unnecessarily complicates the logic an editor needs if you want it to support indentation assists.

(And I think it was a good decision for Python, despite using # ... comments, to use an analogue to /** ... */ for docstrings, with its "If the first statement in a module, class, or function is a multi-line string using the """ ... """ or ''' ... ''' syntax, it's used as a docstring" approach.)

At the same time, when I've had to write C, using /* this */ for a single line is a pain.

Both types of comments have their place and I always configure rustfmt to leave the decision up to me. (If I had the choice, I'd normalize doc comments to multi-line and non-doc comments to single-line to encourage documentation to be verbose and code to be factored in a way suited to concise comments.)

Off-Shoot Idea: How about some syntactic sugar for #[doc="..."] to make life simpler? Then we could simply drop all kinds of documentation comments and use attributes directly. Just a thought.

Could you clarify what you envision "syntactic sugar" to entail? I'm imagining "replacement for /** ... */" and the only things I can imagine in that role provide significantly more visual noise for the same use cases.

[steveklabnik]

I believe at this point, with the RFCs being turned down, the status quo is what's going to remain. as such, i don't think we need to track this.