I mostly agree to Niko's comments, but I'd like to point out one issue
with function docs. Given the following code:
~~~~
/// This is a doc comment with two paragraphs.
///
/// Not actually.
pub fn a() {
}
/**
* This is a doc comment with two paragraphs.
*
* Really.
*/
pub fn b() {
}
~~~~
...rustdoc produces two paragraphs for `b` but one paragraph for `a`
(behaves as if there are no empty lines). I was assumed that it was by
design until now, but it now feels like a bug. (I'll open an issue if
it is indeed considered a bug.)
Niko Matsakis <n...@alum.mit.edu> wrote:
> # Function docs
>
> I prefer putting the function comment *inside* the fn rather than in
> front. However, I am probably alone on this point, so I'm prepared to
> lose this fight. Anyhow, if we are going to place comments in front of
> the function, I think we should encourage `///` comments in favor of the
> `/**..*/`. That is, prefer this:
>
> /// Function comment
> /// More function comment
> fn foo() { ... }
>
> To this:
>
> /**
> * Function comment
> * More function comment
> */
> fn foo() { ... }
>
> My reasons:
>
> 1. No wasted lines (unlike /** ... */ which wastes two lines).
> 2. If you include a code example inside the `///` comment, you can use
> `/* ... */` within the comment without triggering errors.
> 3. It just looks better to my eyes ;)
--
-- Kang Seonghoon | Software Engineer, iPlateia Inc. | http://mearie.org/
-- Opinions expressed in this email do not necessarily represent the
views of my employer.
--
_______________________________________________
Rust-dev mailing list
Rust-dev@mozilla.org
https://mail.mozilla.org/listinfo/rust-dev
