search

rust-lang / rfcs

RFCs for changes to Rust
https://rust-lang.github.io/rfcs/
Apache License 2.0
5.98k stars 1.57k forks source link

Deprecate some kinds of doc comments #1371

Closed nrc closed 6 years ago

nrc commented 9 years ago

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 commented 9 years ago

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 commented 9 years ago

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

gsingh93 commented 9 years ago

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

alfiedotwtf commented 9 years ago

@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 commented 9 years ago

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 commented 9 years ago

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.

:+1: from me (although I would like to see //! remain)

Gankra commented 9 years ago

:fire: :skull: Death to /*! :skull: :fire:

steveklabnik commented 9 years ago

I'm :+1: 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 commented 9 years ago

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

Manishearth commented 9 years ago

:+1: 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 commented 9 years ago

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 commented 9 years ago

:+1: for removing block doc comments

huonw commented 9 years ago

Discussed previously: https://github.com/rust-lang/rust/issues/6782 which was moved to https://github.com/rust-lang/rfcs/issues/287.

SimonSapin commented 9 years ago

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 commented 9 years ago

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 commented 9 years ago

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

AngusP commented 9 years ago

@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 commented 9 years ago

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 commented 9 years ago

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 commented 9 years ago

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 commented 8 years ago

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

pradyunsg commented 8 years ago

I disagree.

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

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 commented 6 years ago

@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 commented 6 years ago

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 commented 6 years ago

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.