John, I would suggest requiring *exactly* three slashes for a doc comment (or *exactly* two stars for a /** -- */ style doc comment). This matches with Doxygen's parsing (I think), and makes both the examples below parse correctly.
Erik On 5/1/2013 11:29 AM, John Clements wrote: > Currently, the set of doc comments includes (among other things) lines > beginning with three slashes, *unless* they're entirely slashes. Presumably, > this is to ensure that things like > > ///////////// > // Time to go get some coffee! > //////////// > > ... aren't parsed as two doc comments consisting entirely of slashes (with an > ignored comment in between. > > This makes sense to me. > > However, it also means that things like > > /// My awesome procedure > /// > /// - does everything, > /// > /// - is kinda slow. > > is parsed as three lines of doc comments, rather than five. > > I propose that '///' should be treated as a doc comment, essentially by > special-casing it. > > The risk is that certain existing normal-comments would be changed into > doc-comments, causing compilation failure. If people think this change is > (otherwise) sensible, I'll naturally check it locally on my tree before > inflicting it on anyone else. > > Best, > > John > > _______________________________________________ > 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
