I like ///, although I would like to standardize on comments before/after the method declaration.
For people who know more about emacs than me: could we get rust-mode support for placing a '///' on the newline? One point in favor of putting the docs before the signature is that it'd be consistent with how comments would appear on fields.. On Tue, Aug 27, 2013 at 7:06 AM, Oren Ben-Kiki <[email protected]> wrote: > 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 > [email protected] > https://mail.mozilla.org/listinfo/rust-dev > >
_______________________________________________ Rust-dev mailing list [email protected] https://mail.mozilla.org/listinfo/rust-dev
