Remove some kinds of doc comments

[nrc]

Closes #287, #1371.

[wthrowe]

I believe currently all the comment forms are defined to desugar to the attribute forms, so it seems like removing the latter would break things. I think they are currently the only way to handle documentation in macros, for instance.

I don't think that humans should be writing the attribute forms or that things like rustfmt should be expected to handle them, but they seem to be a useful representation for processing code programatically.

[nrc]

@wthrowe doc comments are treated as attributes, but it's a messy hack and should be re-done anyway (we should distinguish doc comments in the AST and lower them to attributes in the HIR, or something). I don't think that needs to affect the surface syntax in any way.

I'm curious about the macros thing - aiui, doc comments work fine in macro_rules macros and it's only an issue in syntax extensions because they have access to the gross AST. I might be wrong here though.

So, I don't see any reason for attribute comments to be exposed to the user at all (including via tools or syntax extensions).

[sfackler]

@nrc they work fine in macros but the macro definition has to treat the comments as attributes: https://github.com/sfackler/rust-postgres/blob/master/src/types/mod.rs#L101. We'd need to add a matcher for doc comments if the desugaring was changed.

[brendanzab]

Removing the #[doc=""] attribute is a breaking change, unlike removing /** */ and /*! */. Perhaps cutting it down to removing just /** */ and /*! */ would improve the chance of this getting through...?

[brendanzab]

I would also be interested in some hard data about how many crates use each of the mentioned forms, and whether we could do some automated PRs to amend them.

[tomjakubowski]

One thing I'd still like to see in the documentation system is the ability to reference external Markdown files for the purpose of documenting items. It would be particularly nice for crate-level or module-level documentation, which tend to (and should!) be rather long and full of details, explanation, and examples:

// lib.rs
#![doc(file="some_long_prose.md")]

mod foo;
mod bar;

pub use foo::Foo, bar::Bar;

Does this RFC still allow a feature like that in the future?

[nrc]

@tomjakubowski sure, that seems pretty orthogonal to this issue - we could always add such an attribute (hopefully with scoped attributes in the future, it wouldn't even need to be a language issue).

[DanielKeep]

... why?!

I use block doc comments because they're significantly easier to deal with than constantly having to manually reflow and re-comment line comments (which are for lines not blocks). Removing them just makes my life (and anyone who prefers them) more difficult for, from what I can tell, basically no benefit.

Removing the #[doc] attribute makes it impossible to pass documentation through macros. Removing it just makes the life of everyone who uses macros more difficult for, from what I can tell, limited to no benefit, given that doc comments are internally rewritten to #[doc] attributes anyway.

There are too many kinds of doc comments, they are confusing for users ...

This is an unbelievably low bar. As in, I don't seriously believe this is an actual reason.

... and tools.

Now this, I would buy... if it hadn't taken me all of one or two hours to support both in cargo script.

They're there. They're useful. Just... why?!

[netvl]

makes it impossible to pass documentation through macros

I think using doc comments in macros where metadata tokens are expected works now. For example, this definition produces correct rustdoc output, with all pieces of documentation in their place.

[chris-morgan]

Doc comments as purely sugar for attributes works really well. This can tie in really well with #[cfg_attr], with examples shown in http://chrismorgan.info/blog/rust-cfg_attr.html (the bonus section).

[suhr]

👎
Block doc comments looks much cleaner for multi-paragraph documentation.

[Manishearth]

I don't like the idea of removing #[doc=""]. The doc attribute has other parameters too, and it makes sense to treat it as an attribute so that macros can move it around (see: bitflags).

👍 for the rest

sheds a single tear for the block doc comment 💧

[nrc]

@Manishearth, assuming doc comments are still associated with nodes in the AST, why are attributes easier for macros to deal with? (I'm assuming that doc comments would be lowered to attributes in the HIR, but kept explicit in the AST, but would be fairly identical to attributes, just distinguishable).

[nrc]

@chris-morgan I don't think anything in the RFC would break that, in particular I'm not proposing any changes to the representation of doc comments in the compiler (perhaps only superficial changes to their representation in the AST).

[Manishearth]

Macros operate on the AST and not the HIR.

So I can capture all attributes, including doc comments, using a $(#[$x:mitem])+ specifier

[nrc]

@DanielKeep why? - because we do everything we can to make the language small and only have multiple ways of doing things when there is a real motivation for doing so. IMO, the different kinds of doc comments are not pulling their weight in this respect.

Easier for users means a shorter, less confusing section in tutorials for beginners, less choice and thus variation between projects, etc.

Easier for tools means fewer gotchas and smaller, easier to debug and maintain tools.

[nrc]

@Manishearth (in reply to the earlier comment) removing the attribute form doesn't mean that we have to change the representation in the AST (although I was imagining we would, your later comment is some motivation for not doing so).

In reply to the second comment, it seems somewhat awkward that a macro pattern like that captures a syntactic form which does not match the pattern. I can see why you might want this, but I'm not convinced it's a feature rather than a bug.

[kbknapp]

I didn't even know /*! */ was a thing until now! I absolutely hate /// for long documentation or docs that change frequently, which requires manual reflowing where changing a sentence can have tedious cascading changes. If that's removed I'd be upset after having just found a new Favorite Thing 😄 Everything else doesn't affect me as much, minus regular block comments for testing.

[DanielKeep]

@nrc

IMO, the different kinds of doc comments are not pulling their weight in this respect.

In my opinion, line doc comments are vanishingly rare because proper documentation is almost always going to involve more than a single line and, in those few cases, wrapping said line in a block isn't that big a deal.

So yes, let's kill single line doc comments!

Keeping the language minimal is, in general, something I approve of. But documentation is not an area to skimp on. The last thing you want is to be putting up roadblocks to getting people to write more and better documentation. Line doc comments require either significantly more time and effort, or a specialised editor that's been contorted to do unnatural things with them.

I have never, in my life, found an editor that made "block line" comments sane to deal with. If you're fine with them, well, fantastic. If the style guide wants to direct people to using them, OK. You actually take them away, however, and I'm just that much less likely to bother writing documentation when it means endlessly munging them by hand.

[Manishearth]

So yes, let's kill single line doc comments!

Except that's the kind of doc comment that everyone seems to be using.

I dunno, Sublime with Alt-Q works fine on wrapping block comments. I think vim does too.

[kbknapp]

Except that's the kind of doc comment that everyone seems to be using.

I could be mistaken, but I believe that's because its been advertised as
the preferred method and block comments were frowned upon.

[bstrie]

This discussion demonstrates once again why we've never ever managed to pare down our menagerie of doc comments. :P

I'll just leave this here: http://c2.com/cgi/wiki?WadlersLaw

[bstrie]

@nrc I hereby propose you break the eternal deadlock by actually and at last proposing some magic that would let us remove inner doc comments, instead of removing either line or block form. That would at least be a new and exciting bikeshed compared to this dreadfully bruised horse carcass. :)

[tbu-]

gqq for reflowing doc comments in vim.

[istankovic]

I agree with all @DanielKeep has said and would miss the non-prefixed block comments. While I appreciate the desire to keep the language minimal and easy for the users, I do not think this
should be done at the expense of usability and usefulness.

[AlisdairO]

FWIW I really value block doc comments. It's unclear to me why anyone would want to use single line comments for any form of substantial documentation - it's just extra work for no obvious benefit.

[BurntSushi]

As I said before, I do like block doc comments for module docs. I would mourn their loss, but not for too long.

With that said, there is an ancient utility called par which can do any kind of line wrapping you like. I use it all the time to remove most of the pain resulting from writing line comments. (Without some kind of automatic reflowing, I would be up in arms about losing block doc comments, which I think is a pretty good argument for keeping them IMO, because not everyone may want to fuss with such things.)

Let's say you end up with line doc comments like this:

/// Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam tincidunt, turpis id elementum ullamcorper, felis ante faucibus ante,
/// in porta neque
/// neque in turpis. Vivamus purus dolor,
/// tempus nec maximus nec, molestie ut erat.

I'm an 80 column zealot, so I run this command:

# See man page for configuring par. Have fun!
$ par T4 B=. 79qr < line-comments 
/// Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam tincidunt,
/// turpis id elementum ullamcorper, felis ante faucibus ante, in porta neque
/// neque in turpis. Vivamus purus dolor, tempus nec maximus nec, molestie ut
/// erat.

All you then need to do is configure your editor to replace highlighted text with the output of an arbitrary command. For vim, I have vmap \g !par T4 B=. 79qr<CR>. So I just highlight and type \g. (I've found vim's built in automatic reflowing to perform worse than par.)

[polyfractal]

Except that's the kind of doc comment that everyone seems to be using.

I personally never knew alternatives existed (not discussed in the book, etc), and have endured writing long essays using ///not because I really wanted to, but because it was the only option known to me.

At the end of the day I don't really care, I'll keep putting up with /// if that's the only option. But now knowing a block-level comment exists, I'll certainly prefer that.

If I had to vote (which luckily I dont! :) ), I'd be happy seeing it simplified down to two doc comments: outer-line + outer-block.

[BurntSushi]

@BurntSushi with a textwidth setting, vim's = works just fine as well.

Yeah, in that example. Probably for everything related to line doc comments too. It's good. I just can't remember now where it got hung up. I switched all line wrapping to par years ago. :-)

[mdinger]

FWIW, multi-line doc comments weren't even really documented decently at all until recently (I had to guess at how they were closed besides perhaps not realizing they existed). The book avoids using them because they're not the official style so even if they aren't used much, the deck was loaded against them to begin with. Usage statistics aren't a very useful indicator here since by all indication, official policy is to hinder their usage.

Stating multiple different types of comments is too complex for users to handle is basically a silly argument. No one ever complained that teal, aqua, navy, and royal blue as colors for blue are too complicated for people to handle and there are more colors than those. No one complains that we can walk, skip, run, or crawl which all stand for modes of physical transportation. People are very adept at comprehending a multitude of subtly different words properly.

The improvements documentation would see from removing these are basically non-existent. Doc comment documentation is basically independent of all sections except comments and not difficult anyway. Consolidating all community commenting to a single type would be effective but not useful. You're removing something easy to understand which isn't ambiguous.

Even if it was difficult to disambiguate between different comment types it still wouldn't matter. Almost all users write comments in an editor with syntax highlighting. Any comment will be syntax highlighted accordingly and so should be clear. Even if that wasn't the case, context should be highly effective at highlighting that a paragraph clearly isn't dense logical code. Even if that also wasn't the case, the compiler would point out that your poem (or paragraph or whatever) isn't valid for some reason and you'd comment it out.

[niconii]

Big 👎.

I'm not a fan of removing features for no large benefit. Block doc comments are not confusing and not hard to support. The fact that there are ways around most of the pain that removing block doc comments would cause does not in itself justify the removal of them. "It's not that bad" does not mean it's good either.

(By the way, with the idea of all block comments being removed having been touched upon in #1371, I'd like to also mention I am completely against removing normal block comments as well.)

[birkenfeld]

👎 - this proposal feels like "simplify for simplification's sake", rather than addressing real confusion/friendliness issues among new users. I feel that much more can be gained by working on compiler diagnostics and messages, especially w.r.t. borrows and traits.

[nikomatsakis]

I guess my overall feeling is indifference. Obviously I do feel like we should avoid backwards incompatibility in general, so in that sense I am not a big fan of this RFC. However, it's worth noting that the RFC itself proposed only deprecating the other comment forms, and then perhaps removing them at some future date. Ubiquitous use of rustfmt may have the same effect, if it starts to rewrite comments into the approved form. So perhaps we should just revisit this in the future, if that utopia (or dystopia, depending on your POV) has come to pass.

Personally, I'm still a big fan of writing comments with /*!, since it moves the comment inside the fn body, allowing me to easily peruse the function's name, argument names, and argument types at a glance, and only dig into more detailed documentation if I think I have to. Since I tend to read code (and not rustdoc) a lot, this is a very helpful thing. But I have kind of given up on arguing for this, since people seem to really prefer /// for a variety of reasons, which I admit are also valid.

[tbu-]

@nikomatsakis //! also works inside the function body.

[nikomatsakis]

@tbu- yes, but I at least find the ! distracting in large quantities. I guess I could get use to it.

[hauleth]

@nikomatsakis I have never thought about that. It seems as really nice idea.

[nikomatsakis]

Hear ye, hear ye. This RFC is now entering final comment period.

[aturon]

I largely agree with the sentiments express on this thread. Regardless of its merits, we shipped these features in 1.0 and need to have a pretty strong reason (and consensus) to deprecate them. (I don't personally use these forms and would not miss them, but that's beside the point.)

For this to be a realistic path, I think the first step would be getting consensus around comment conventions via widely-used rustfmt defaults that don't use these forms. If the vast majority of the community was using rustfmt in that way, then deprecating these comment forms might be plausible.

[bluss]

#[doc] can be used to paste together nice doc comments out of parts, useful in macros if you have a zillion trait impls (example).

[zetok]

So yes, let's kill single line doc comments!

Except that's the kind of doc comment that everyone seems to be using.

I could be mistaken, but I believe that's because its been advertised as
the preferred method and block comments were frowned upon.

Yeah, makes you wonder why there's a strong "preference" by compiler devs to use one, and not use the other.

I use block docs, and see no reason to not to. Check, it would be a lot more preferable for me to just not update to (IMHO) insane Rust version, rather than not using them. I.e. if one useful thing would be broken for no reason, who knows what other, even more useful things would stop working, or would start to malfunction.

https://github.com/zetok/tox/blob/bacaf781019bb2622446e5d3e1d2ac16b7b71325/src/lib.rs#L20 ← here you have a use case.

(…) they are confusing for users (…)

Are they? And if so, why would that be? Perhaps it's because there's some weird pressure from Rust lang devs to use line docs, and conveniently forget about block docs?

If I may, I'd suggest to improve docs if they are confusing, and educate people about the _features_ they can use, rather than removing something useful just because you've failed to document & spread the word about the feature properly. If you're not convinced about the failure, feel free to look at comments even on this proposal, where people genuinely didn't know about the feature.

Check, if not for @suhr who mentioned the feature to me when I was starting to learn Rust (1.0) I wouldn't know that I can do docs the better way. Just because docs sucked.

Basically what @mdinger wrote.

We can provide a tool (based on Rustfmt) to automatically convert all invalid doc comments to valid ones.

No. What I notice, is some weird trend going on in Rust community to "do things *our* way or go away". You might want to ponder on that, and consider how it reflects on Rust.

For this to be a realistic path, I think the first step would be getting consensus around comment conventions via widely-used rustfmt defaults that don't use these forms.

Since when that thing became "widely-used" or an unbiased indicator of conventions?

[ahicks92]

I'm really against this. Though my reason is odd.
The thing is, I'm a blind programmer. Reading my own docs with //! or /// at the beginning of every single line is beyond annoying. If I want indentation indication, that format doesn't let my screen reader read it to me because indentation is defined as whitespace at the beginning of the line.
Please keep this. I don't particularly see the problem with having at least /*! !*/ and /** */. you can kill the explicit attribute syntax all you want, but killing these would make my life unnecessarily difficult.
I know that we can't all make the world conform for blind people, but figured it would be worth saying something; this is important to me and probably to anyone else blind who might adopt Rust in the future.

[aturon]

@camlorn Thanks so much for this feedback!

As a separate point, if there are other things we can do to make Rust, its forums or our website more accessible to you, I'd love to hear about it.

[ahicks92]

You guys are pretty good, as long as no one decides that we really need to take the emoji error handling RFC seriously. I'll be reporting stuff against playground at some point, but this is the first one where I can't work around the annoyance by changing some settings while programming. Given that I don't see how there's a maintenance burden from keeping them, I figured I'd pop out of the woodwork to say something.
Also worth mentioning that I do actually use /**/ to block out code as well. I'm not sure if this is blindness specific or not--I'm not familiar enough with the sighted workflow to know how it compares to mine. But /**/ ends up being less keystrokes for me. Unfortunately, Vim and Emacs and the like are inaccessible for complicated reasons; I end up stuck with notepad++.

[pnkfelix]

My opinion: The argument put forth in #1373 (comment) by @camlorn makes a strong case for not accepting this RFC.

I will admit that I don't often consider the needs of blind programmers (and I now wonder how much material we put out in presentations etc that relies on visual diagrams to explain lifetimes et cetera). I'm glad to see people pointing out issues like this.

[tbu-]

@camlorn How much does using /** actually help if most other crates use //! doc comments?

[ahicks92]

I can deal with //! comments. It's not unreadable, just very annoying.
For crates that aren't my projects, though, I use the HTML docs like
everyone else. The HTML docs are much less annoying than browsing the
source. I personally consider packages without HTML docs hosted
somewhere to be immature in any language, though admittedly I count as
an early adopter at the moment and should perhaps relax this heuristic
for Rust as everything is shiny and new in this corner of the internet
anyway. If you're thinking I get all my docs by reading code, that's
very far from the truth.

But for my own stuff, I want the choice. Even I use single-line
comments, but only if it's a line or two; after that, I go for block
very quickly.

If someone provides a good argument for this then I'll go away, but this
entire thing feels like doing something for the sake of doing something
and I don't really see the benefit to any of it but removing the
attribute syntax. I have a concrete reason to want it not done. I
could live with it if it was done, but it would annoy me greatly.

To put this another way:

//This is
//a long
//sample comment

Is read as "Slash slash This is slash slash a long slash slash sample
comment." The longer the comment gets, the more redundant syllables get
added. Blank lines are supposed to be silent. With this style of
comment, blank lines are read as "slash slash." Imagine if someone tried
to read comments out loud to you and insisted on doing that. You can
still understand it, sure, but you'd stop them very quickly. If I want
to set my screen reader to not read slashes, that's fine, but now it's
not going to read the division operator and the procedure involves two
menus and finding slash in the dialog that contains the huge list of
punctuation.

It's kind of hard to explain my heuristic for which style I use where in
C++, because you're talking about something that's very nondeterministic
and for which I've never given it a concrete rule. It depends on
comment size, but also content. Sometimes the info that this line is a
comment is important and having the // up front shouting that you're
still arrowing past comments is helpful because you don't have to
consider the line's content. But sometimes it's a long explanation and
the explanation is important, whereupon whichever prefix I'm using just
gets in the way. SO I opt not to have it once my comments are over a
couple lines and then put the closing */ on a line by itself, because
then you have somewhere to land that says the equivalent of "end comment."

On 4/6/2016 14:57, tbu- wrote:

@camlorn https://github.com/camlorn How much does using |/**|
actually help if most other crates use |//!| doc comments?

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#1373 (comment)

[Centril]

Big 👎 on this RFC. Rust should keep /** */ style comments mainly because it is almost used in every other C-type language. Consistency with other languages creates familiarity and is great to make the language easier to understand.

If anything, /** */ should be mentioned and promoted as the default way of documenting/commenting.

[ticki]

@Centril That is not what this RFC is about.

[nikomatsakis]

We discussed this in the @rust-lang/lang meeting and we have decided not to accept this RFC. The basic reasoning is that this sort of deprecation is not really necessary, as it doesn't simplify the compiler in particular, and we must (for backwards compatibility) retain these various forms of comments anyhow. And of course the argument that /* */ comments can help for accessibility reasons is another point in their favor. Therefore, I am going to close this RFC.