On May 1, 2013, at 6:50 PM, Erik S wrote: > 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.
Both of these restrictions make sense to me. I took a quick look at the current tree, grepping for '////'. Here's what I got: jclements-09740:~/tryrust clements> git grep '////' * src/librustc/middle/subst.rs://///////////////////////////////////////////////////////////////////////// src/librustc/middle/subst.rs://///////////////////////////////////////////////////////////////////////// src/librustc/middle/subst.rs://///////////////////////////////////////////////////////////////////////// src/librustc/middle/trans/debuginfo.rs://////////////// src/rt/msvc/inttypes.h://///////////////////////////////////////////////////////////////////////////// src/rt/msvc/stdint.h://///////////////////////////////////////////////////////////////////////////// src/test/pretty/doc-comments.rs:////////////////////////////////// src/test/pretty/doc-comments.rs:////////////////////////////////// None of these include any non-slash characters, and are therefore parsed correctly (based on my inspection) as non-doc-comments. They would also be parsed correctly by the restricted form (doc comments must have exactly three slashes. I took a look at '/***', as well, and got even more interesting results: jclements-09740:~/tryrust clements> git grep '/\*\*\*' * doc/prep.js:/*** src/libcore/cast.rs:/**************************************************************************** src/libcore/unstable.rs:/**************************************************************************** src/libcore/unstable.rs:/****************************************************************************/ src/libstd/arc.rs:/**************************************************************************** src/libstd/arc.rs:/**************************************************************************** src/libstd/arc.rs:/**************************************************************************** src/libstd/arc.rs:/**************************************************************************** src/libstd/sync.rs:/**************************************************************************** src/libstd/sync.rs:/**************************************************************************** src/libstd/sync.rs:/**************************************************************************** src/libstd/sync.rs:/**************************************************************************** src/libstd/sync.rs:/**************************************************************************** src/libstd/sync.rs: /************************************************************************ src/libstd/sync.rs: /************************************************************************ src/libstd/sync.rs: /************************************************************************ src/rt/rust_upcall.cpp:/********************************************************************** src/rt/rust_upcall.cpp:/**********************************************************************/ src/rt/rust_upcall.cpp:/********************************************************************** src/rt/rust_upcall.cpp:/********************************************************************** src/rt/rust_upcall.cpp:/**********************************************************************/ src/test/pretty/doc-comments.rs:/********************************/ src/test/pretty/doc-comments.rs:/********************************/ The first of these is apparently intended to be a docstring, so putting the restriction in place would have missed this one. On the other hand, all of the ones that start with a lot of stars but don't end with a slash *are* currently parsed as docstrings, and (at least in the cases I looked at) almost certainly shouldn't be. So, I think that this restriction would also improve the quality of our code. Anyone object to changing the parser in this way? To be clear, these two restrictions are (in my view) orthogonal to other possible changes. I'd still be delighted to get rid of some of the doc-string forms. John > > 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 _______________________________________________ Rust-dev mailing list [email protected] https://mail.mozilla.org/listinfo/rust-dev
