I prefer using /// for comments before functions and types, and ///! for
comments following fields:
/// ...
pub struct Foo {
foo: int, //! ...
}
(BTW, it would be nice to document function arguments:
/// ...
pub fn foo(
foo: int, //! ...
) {
...
}
But rustdoc doesn't have the concept of a doc for an argument. Oh well.)
At any rate, //! allows structs to stay compact but still document the
fields, as opposed to having a /// before each one which takes double the
amount of lines. I actually use /// for struct fields, because rustdoc
doesn't using allow //! this way today (it says "expected outer comment").
A bug, I guess? So I only use //! at the top to document the whole module.
The main reason I use //-style everywhere is that this way I can safely use
/* ... */ to comment out chunks of code. I don't comment code chunks a lot,
but when I need to, it is good to know one can just do it without worrying
about nesting /* ... */.
If /* ... */ allowed nesting, I'd probably still prefer //-style - The '*'
seem visually noisy, it takes up extra lines (in multi-line comments), and
I'm never comfortable when I see:
/*!
* foo
*/
Whether it would end up meaning:
// * foo
Or (more likely):
/// foo
_______________________________________________
Rust-dev mailing list
Rust-dev@mozilla.org
https://mail.mozilla.org/listinfo/rust-dev
