Comments section doesn't describe the multi-line comment syntax

[gsauthof]

The Comments Section of the 2nd edition doesn't mention the /* */ multi-line comment syntax:

http://rust-lang.github.io/book/second-edition/ch03-04-comments.html

It even states:

In Rust, comments must start with two slashes and continue until the end of the line. For comments that extend beyond a single line, you’ll need to include // on each line, like this:

And closes with:

That’s all there is to comments. They’re not particularly complicated.

But all this conflicts with the Rust reference:

https://doc.rust-lang.org/reference/comments.html

(which btw also mentions doc comments ...)

Rust seems to support multiline comments since 7 years:

rust-lang/rust#66

[steveklabnik]

Yes, this is on purpose. The Book is supposed to show idiomatic Rust, and to teach you the language, not show you every last nook and cranny of the language. Multi-line comments are not considered idiomatic, and so aren't described in the book. Thanks for reporting though!

[gsauthof]

Interesting.

Are there specific reasons for considering /* */ as non-idiomatic Rust?

I'm asking since /* */ style comments aren't obviously ugly nor error prone. For example, I've never heard somebody complain about them. Also, the Rust reference and grammar specify them without any word of caution.

Describing the two Rust commenting styles is far away from showing 'every last nook and cranny of the language'.

Omitting certain advanced features from an 'introductory book about Rust' is fine.

But this section does more. It lists several false statements:

'In Rust, comments must start with two slashes and continue until the end of the line.'

Wrong. Correct is: In Rust, comments may also start with /* and those continue until the next matching */.

'That’s all there is to comments.'

Wrong. Correct is: That isn't all there is to comments. There is more. There are /* */ multi-line comments. And comments with documentation semantics.

'They’re not particularly complicated.'

Wrong. Correct is: // and /* */ style comments are very simple - even more so, because they are available in so many popular languages. But doc-comments arguably can be seen as kind of complicated.

[lazarillo]

@gsauthof I am new to Rust, so I cannot speak to why multi-line is considered non-idiomatic within Rust, specifically.

However, I have noticed in the last few years, as generated documentation has become easier to implement, that there is an effort to make comments shorter and simpler. In fact, there is a mild rant against using too many comments within Python because user documentation can also be embedded within the code. I've seen similar suggestions with Javascript and creating JSDocs.

These are higher level languages, but maybe the same thing is true for a "brand new" low level language like Rust?

[ThomasR]

The Book is supposed to show idiomatic Rust, and to teach you the language, not show you every last nook and cranny of the language.

This is not consistent with Appendix B, where the block comments show up. Does that mean the appendix should be removed from the book?