Repository navigation
Add a section about code documentation/comments #40
Description
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
Activity
japaric commentedon May 1, 2014
Not sure we want a whole chapter on comments. (But I can be persuaded)
We could introduce them properly in the "Hello World" chapter.
This will be covered in the rustdoc chapter (which is already in the wishlist)
Maybe this can be part of the rustdoc chapter.
kud1ing commentedon May 2, 2014
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,enumetc. either.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 commentedon May 2, 2014
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 commentedon May 3, 2014
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:
will be
Many tools like Eclipse JDT will do this instead:
which makes it hard to re-enable the block as it was.
japaric commentedon Jun 17, 2014
Closing in favor of #107 and #108