New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove some kinds of doc comments #1373

Closed
wants to merge 1 commit into
from

Conversation

Projects
None yet
@nrc
Member

nrc commented Nov 20, 2015

Closes #287, #1371.

@nrc nrc added the T-lang label Nov 20, 2015

@nrc nrc self-assigned this Nov 20, 2015

@wthrowe

This comment has been minimized.

Show comment
Hide comment
@wthrowe

wthrowe Nov 20, 2015

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.

wthrowe commented Nov 20, 2015

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

This comment has been minimized.

Show comment
Hide comment
@nrc

nrc Nov 20, 2015

Member

@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).

Member

nrc commented Nov 20, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@sfackler

sfackler Nov 20, 2015

Member

@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.

Member

sfackler commented Nov 20, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@brendanzab

brendanzab Nov 21, 2015

Member

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...?

Member

brendanzab commented Nov 21, 2015

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

This comment has been minimized.

Show comment
Hide comment
@brendanzab

brendanzab Nov 21, 2015

Member

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.

Member

brendanzab commented Nov 21, 2015

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

This comment has been minimized.

Show comment
Hide comment
@tomjakubowski

tomjakubowski Nov 22, 2015

Contributor

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?

Contributor

tomjakubowski commented Nov 22, 2015

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

This comment has been minimized.

Show comment
Hide comment
@nrc

nrc Nov 23, 2015

Member

@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).

Member

nrc commented Nov 23, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@DanielKeep

DanielKeep Nov 23, 2015

... 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?!

... 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

This comment has been minimized.

Show comment
Hide comment
@netvl

netvl Nov 23, 2015

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.

netvl commented Nov 23, 2015

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

This comment has been minimized.

Show comment
Hide comment
@chris-morgan

chris-morgan Nov 23, 2015

Member

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).

Member

chris-morgan commented Nov 23, 2015

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

This comment has been minimized.

Show comment
Hide comment
@suhr

suhr Nov 24, 2015

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

suhr commented Nov 24, 2015

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

@Manishearth

This comment has been minimized.

Show comment
Hide comment
@Manishearth

Manishearth Nov 24, 2015

Member

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 💧

Member

Manishearth commented Nov 24, 2015

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

This comment has been minimized.

Show comment
Hide comment
@nrc

nrc Nov 24, 2015

Member

@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).

Member

nrc commented Nov 24, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@nrc

nrc Nov 24, 2015

Member

@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).

Member

nrc commented Nov 24, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@Manishearth

Manishearth Nov 24, 2015

Member

Macros operate on the AST and not the HIR.

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

Member

Manishearth commented Nov 24, 2015

Macros operate on the AST and not the HIR.

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

@nrc

This comment has been minimized.

Show comment
Hide comment
@nrc

nrc Nov 24, 2015

Member

@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.

Member

nrc commented Nov 24, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@nrc

nrc Nov 24, 2015

Member

@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.

Member

nrc commented Nov 24, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@kbknapp

kbknapp Nov 24, 2015

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.

kbknapp commented Nov 24, 2015

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

This comment has been minimized.

Show comment
Hide comment
@DanielKeep

DanielKeep Nov 24, 2015

@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.

@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

This comment has been minimized.

Show comment
Hide comment
@Manishearth

Manishearth Nov 24, 2015

Member

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.

Member

Manishearth commented Nov 24, 2015

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

This comment has been minimized.

Show comment
Hide comment
@kbknapp

kbknapp Nov 24, 2015

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.

kbknapp commented Nov 24, 2015

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 comment has been minimized.

Show comment
Hide comment
@bstrie

bstrie Nov 24, 2015

Contributor

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

Contributor

bstrie commented Nov 24, 2015

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

This comment has been minimized.

Show comment
Hide comment
@bstrie

bstrie Nov 24, 2015

Contributor

@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. :)

Contributor

bstrie commented Nov 24, 2015

@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-

This comment has been minimized.

Show comment
Hide comment
@tbu-

tbu- Nov 24, 2015

Contributor

gqq for reflowing doc comments in vim.

Contributor

tbu- commented Nov 24, 2015

gqq for reflowing doc comments in vim.

@istankovic

This comment has been minimized.

Show comment
Hide comment
@istankovic

istankovic Nov 24, 2015

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.

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

This comment has been minimized.

Show comment
Hide comment
@AlisdairO

AlisdairO Nov 24, 2015

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.

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

This comment has been minimized.

Show comment
Hide comment
@BurntSushi

BurntSushi Nov 24, 2015

Member

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.)

Member

BurntSushi commented Nov 24, 2015

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.)

@m4rw3r

This comment has been minimized.

Show comment
Hide comment
@m4rw3r

m4rw3r Nov 24, 2015

One use I have for the #[doc=""] annotation is to use it with cfg_attr to enable/disable different doctests depending on which features have been enabled. Otherwise I will have to write the examples only for the empty feature set and/or avoid testing, compiling and even highlighting the examples at all for the shared parts.

m4rw3r commented Nov 24, 2015

One use I have for the #[doc=""] annotation is to use it with cfg_attr to enable/disable different doctests depending on which features have been enabled. Otherwise I will have to write the examples only for the empty feature set and/or avoid testing, compiling and even highlighting the examples at all for the shared parts.

@Aatch

This comment has been minimized.

Show comment
Hide comment
@Aatch

Aatch Nov 24, 2015

Contributor

What's the reason for removing the block forms instead of the line forms? Block comments are, by definition, for multiple lines. I don't care what people seem to be using. Plenty of people are using all four kinds.

At the end of the day four kinds is not actually that many. There's basically no consensus and I can't see it being worth the effort. As @bstrie says, I doubt this will ever get anywhere. It didn't get anywhere any other time it was proposed.

Contributor

Aatch commented Nov 24, 2015

What's the reason for removing the block forms instead of the line forms? Block comments are, by definition, for multiple lines. I don't care what people seem to be using. Plenty of people are using all four kinds.

At the end of the day four kinds is not actually that many. There's basically no consensus and I can't see it being worth the effort. As @bstrie says, I doubt this will ever get anywhere. It didn't get anywhere any other time it was proposed.

@ticki

This comment has been minimized.

Show comment
Hide comment
@ticki

ticki Nov 24, 2015

Contributor

I get the idea in this proposal, but I don't see the point of removing them with such little gain.

Contributor

ticki commented Nov 24, 2015

I get the idea in this proposal, but I don't see the point of removing them with such little gain.

@steveklabnik

This comment has been minimized.

Show comment
Hide comment
@steveklabnik

steveklabnik Nov 24, 2015

Member

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

I agree with a lot of others on this thread: yeah, there's changes that would be nice to make, but we just can't make these kinds of breaking changes anymore. Huge 👎 here.

Member

steveklabnik commented Nov 24, 2015

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

I agree with a lot of others on this thread: yeah, there's changes that would be nice to make, but we just can't make these kinds of breaking changes anymore. Huge 👎 here.

@polyfractal

This comment has been minimized.

Show comment
Hide comment
@polyfractal

polyfractal Nov 24, 2015

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.

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

This comment has been minimized.

Show comment
Hide comment
@BurntSushi

BurntSushi Nov 24, 2015

Member

@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. :-)

Member

BurntSushi commented Nov 24, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@mdinger

mdinger Nov 24, 2015

Contributor

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.

Contributor

mdinger commented Nov 24, 2015

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

This comment has been minimized.

Show comment
Hide comment
@niconii

niconii Nov 25, 2015

Member

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.)

Member

niconii commented Nov 25, 2015

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 comment has been minimized.

Show comment
Hide comment
@birkenfeld

birkenfeld Nov 25, 2015

👎 - 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.

👎 - 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

This comment has been minimized.

Show comment
Hide comment
@nikomatsakis

nikomatsakis Nov 25, 2015

Contributor

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.

Contributor

nikomatsakis commented Nov 25, 2015

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-

This comment has been minimized.

Show comment
Hide comment
@tbu-

tbu- Nov 25, 2015

Contributor

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

Contributor

tbu- commented Nov 25, 2015

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

@nikomatsakis

This comment has been minimized.

Show comment
Hide comment
@nikomatsakis

nikomatsakis Nov 25, 2015

Contributor

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

Contributor

nikomatsakis commented Nov 25, 2015

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

@hauleth

This comment has been minimized.

Show comment
Hide comment
@hauleth

hauleth Dec 8, 2015

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

hauleth commented Dec 8, 2015

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

@nikomatsakis

This comment has been minimized.

Show comment
Hide comment
@nikomatsakis

nikomatsakis Mar 21, 2016

Contributor

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

Contributor

nikomatsakis commented Mar 21, 2016

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

@aturon

This comment has been minimized.

Show comment
Hide comment
@aturon

aturon Apr 1, 2016

Member

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.

Member

aturon commented Apr 1, 2016

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

This comment has been minimized.

Show comment
Hide comment
@bluss

bluss Apr 2, 2016

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

bluss commented Apr 2, 2016

#[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

This comment has been minimized.

Show comment
Hide comment
@zetok

zetok Apr 4, 2016

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?

zetok commented Apr 4, 2016

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?

@camlorn

This comment has been minimized.

Show comment
Hide comment
@camlorn

camlorn Apr 5, 2016

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.

camlorn commented Apr 5, 2016

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

This comment has been minimized.

Show comment
Hide comment
@aturon

aturon Apr 5, 2016

Member

@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.

Member

aturon commented Apr 5, 2016

@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.

@camlorn

This comment has been minimized.

Show comment
Hide comment
@camlorn

camlorn Apr 5, 2016

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++.

camlorn commented Apr 5, 2016

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

This comment has been minimized.

Show comment
Hide comment
@pnkfelix

pnkfelix Apr 6, 2016

Member

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.

Member

pnkfelix commented Apr 6, 2016

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-

This comment has been minimized.

Show comment
Hide comment
@tbu-

tbu- Apr 6, 2016

Contributor

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

Contributor

tbu- commented Apr 6, 2016

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

@camlorn

This comment has been minimized.

Show comment
Hide comment
@camlorn

camlorn Apr 6, 2016

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)

camlorn commented Apr 6, 2016

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)

zetok added a commit to zetok/tox that referenced this pull request Apr 9, 2016

style: convert to block comments whenever possible
Since they're easier to deal with for blind programmers:
rust-lang/rfcs#1373 (comment)
@Centril

This comment has been minimized.

Show comment
Hide comment
@Centril

Centril Apr 12, 2016

Contributor

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.

Contributor

Centril commented Apr 12, 2016

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

This comment has been minimized.

Show comment
Hide comment
@ticki

ticki Apr 13, 2016

Contributor

@Centril That is not what this RFC is about.

Contributor

ticki commented Apr 13, 2016

@Centril That is not what this RFC is about.

@nikomatsakis

This comment has been minimized.

Show comment
Hide comment
@nikomatsakis

nikomatsakis Apr 22, 2016

Contributor

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.

Contributor

nikomatsakis commented Apr 22, 2016

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.

@kelseasy kelseasy referenced this pull request in rust-lang-nursery/fmt-rfcs Mar 22, 2018

Closed

Comment syntax and accessibility #120

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment