I find I have surprisingly strong opinions about this. In particular,
I don't care for any of the options. Rather I prefer option D, which
looks like:
fn foo() {
/*!
* Summary
*
* Body text
*/
}
My reasoning:
- I want the comment INSIDE the function, not outside. Putting the
comment outside obscures the names and arguments. My typical use
case is browsing code, and I find it very helpful to be able to skim
over the names and prototypes, and only dive into the documentation
as needed (you'll note that when people render the docs in HTML,
they lead with the function name and arguments and only provide the
full text when you click on the function).
- Option C (`//!`) also places the comments inside, but I just don't
like it: I find the repeated `!` is hard to read.
- For modules, if there is a long comment, I prefer to move the
comment to a distinct `doc.rs` file. All complex modules SHOULD have
a long comment introducing them at a high-level; submodules should
not (e.g., `borrowck` needs a comment, but `borrowck::check_loans`
does not).
It is quite possible I am alone in these preferences though. =)
Niko
On Sun, Aug 25, 2013 at 09:59:10PM -0400, Corey Richardson wrote:
> Currently there are a few conventions throughout the codebase, and I
> think we need to agree which one to use, at least in the stdlib and
> compilers. This email is the result of me needing to encode some
> heuristics in rustdoc_ng to strip out the comments and keep the text.
>
> So the major conventions I've seen are:
>
> A:
>
> /*! Summary
>
> Body text
>
> */
>
> B:
>
> /**
> * Summary
> *
> * Body text
> */
>
> C:
>
> //! Summary
> //!
> //! Body text
>
> Of course, /*! and //! are interchangable with /** and ///. Now, I
> don't particularly care which one gets picked (B is my favorite for
> longer blocks, C for <= 3 lines), and I especially dislike A, but
> consistency is king.
> _______________________________________________
> 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
