On 04/10/2013 07:22 PM, Kang Seonghoon wrote:
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.)
I consider this 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
_______________________________________________ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
