Add a section about code documentation/comments

[kud1ing]

Mention:

• one-line comments //
• block comments /* */. It seems, they can be nested: https://mail.mozilla.org/pipermail/rust-dev/2014-April/009709.html
• rustdoc-style comments/documentation ///, /** */: https://github.com/mozilla/rust/wiki/Doc-using-rustdoc

[japaric]

Not sure we want a whole chapter on comments. (But I can be persuaded)

one-line comments //

We could introduce them properly in the "Hello World" chapter.

rustdoc-style comments/documentation

This will be covered in the rustdoc chapter (which is already in the wishlist)

block comments /* */. It seems, they can be nested

Maybe this can be part of the rustdoc chapter.

[kud1ing]

Not sure we want a whole chapter on comments. (But I can be persuaded)

In my opinion, sections of the "Foo by example" format should be much smaller than chapters in a tutorial or a book. This format exists because it allows to look up features when needed (either while programming Rust, or when you want to compare Rust features with your favorite programming language). Most tutorials do not have a whole "chapter" on HelloWorld, if/else, enum etc. either.

block comments /* */. It seems, they can be nested
Maybe this can be part of the rustdoc chapter.

That would be a pitty, because it is not related to rustdoc at all.

What is a better place to make people discover that Rust's comment blocks can be nested (which IMO is an awesome feature for disabling/reenabling code)?

[japaric]

Sorry for my lack of excitement about nested block comments, that's caused by the fact that have not used /* */ in any of my rust code. I do code commenting with nerdcommenter in vim, and that always inserts/removes // for me.

However, how I use comments should not impede others from learning that rust has nested block comments. So let's add a chapter on comments (I'll queue it in the wishlist right now). But, I would like to see a useful example about nesting comments (not just some /* You can /* nest */ comments! */ example), before adding such chapter to the book.

[kud1ing]

Well, i'm not excited either, but Rust people removed it first and then missed it and put it back.

It's useful when you want to temporarily disable disabled stuff:

foo
/*
disabled
*/
bar

will be

/*
foo
/*
disabled
*/
bar
*/

Many tools like Eclipse JDT will do this instead:

/*
foo
disabled
bar
*/

which makes it hard to re-enable the block as it was.

[japaric]

Closing in favor of #107 and #108