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.