www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Documentation comments - /// feature request

reply "Unknown W. Brackets" <unknown simplemachines.org> writes:
I'm a fan of the C# style of documentation comments, that is like this:

/// Summary.
///
/// Some longer description of the function being documented.
///
/// Params:
///    foo =     a number, most possibly 42.
///
/// Returns:     a random number based on the answer to the question
///              of life, the universe, and everything.

It seems to me this was once supported, although ddoc.html has always 
listed "///" as a single line documentation comment.

Is there any chance of parsing the above?  I can't really see any reason 
why two ///'s in a row would be parsed differently.  Right now blank 
lines are inserted in between each line of the comments.

Some editors highlight/feature this functionality better.  My main 
reason for using it is that it wastes less vertical space (wasted lines 
for /** and */...), but is no more difficult to spot (since I always 
highlight with colors anyway.)

I can get this mostly myself by setting DDOC_BLANKLINE to nothing, but 
example sections still don't work and I'm not sure if that's used elsewhere.

Thanks,
-[Unknown]
Jan 20 2008
next sibling parent "Jarrett Billingsley" <kb3ctd2 yahoo.com> writes:
"Unknown W. Brackets" <unknown simplemachines.org> wrote in message 
news:fn1jah$2nkh$1 digitalmars.com...
 I'm a fan of the C# style of documentation comments, that is like this:

 /// Summary.
 ///
 /// Some longer description of the function being documented.
 ///
 /// Params:
 ///    foo =     a number, most possibly 42.
 ///
 /// Returns:     a random number based on the answer to the question
 ///              of life, the universe, and everything.

 It seems to me this was once supported, although ddoc.html has always 
 listed "///" as a single line documentation comment.

 Is there any chance of parsing the above?  I can't really see any reason 
 why two ///'s in a row would be parsed differently.  Right now blank lines 
 are inserted in between each line of the comments.

I think it's just a bug.
Jan 21 2008
prev sibling parent reply Jason House <jason.james.house gmail.com> writes:
Unknown W. Brackets Wrote:
 It seems to me this was once supported, although ddoc.html has always 
 listed "///" as a single line documentation comment.
 
 Is there any chance of parsing the above?  I can't really see any reason 
 why two ///'s in a row would be parsed differently.  Right now blank 
 lines are inserted in between each line of the comments.

I've switched to using /** * **/ for the very reason you've mentioned. I'm ok with both styles, but agree that multiple /// is intuitive and should probably be supported better.
Jan 22 2008
parent reply Bill Baxter <dnewsgroup billbaxter.com> writes:
Jason House wrote:
 Unknown W. Brackets Wrote:
 It seems to me this was once supported, although ddoc.html has always 
 listed "///" as a single line documentation comment.

 Is there any chance of parsing the above?  I can't really see any reason 
 why two ///'s in a row would be parsed differently.  Right now blank 
 lines are inserted in between each line of the comments.

I've switched to using /** * **/ for the very reason you've mentioned. I'm ok with both styles, but agree that multiple /// is intuitive and should probably be supported better.

I really prefer things like ///-------------------------- or /**----------------------- or /**======================= But all those print an annoying row of - or = in the generated documentation. :-( The community could probably do a pretty good job of making fixes like this if the tool weren't all rolled into the compiler. --bb
Jan 22 2008
parent reply torhu <no spam.invalid> writes:
Bill Baxter wrote:
  > I really prefer things like
 ///--------------------------
 
 or /**-----------------------
 
 or /**=======================
 
 But all those print an annoying row of - or = in the generated 
 documentation. :-(
 

I think this works, tango uses it: /********************************
Jan 22 2008
next sibling parent Bill Baxter <dnewsgroup billbaxter.com> writes:
torhu wrote:
 Bill Baxter wrote:
  > I really prefer things like
 ///--------------------------

 or /**-----------------------

 or /**=======================

 But all those print an annoying row of - or = in the generated 
 documentation. :-(

I think this works, tango uses it: /********************************

Right. That's the *only* typical "big block" comment style that works. I just don't like it. Looks too heavy to me. In my opinion any repeated punctuation char after /** should be ignored. --bb
Jan 22 2008
prev sibling parent Bill Baxter <dnewsgroup billbaxter.com> writes:
torhu wrote:
 Bill Baxter wrote:
  > I really prefer things like
 ///--------------------------

 or /**-----------------------

 or /**=======================

 But all those print an annoying row of - or = in the generated 
 documentation. :-(

I think this works, tango uses it: /********************************

DMD is the only documentation generator I know of that *can't* handle all of the cases above. NaturalDocs, JavaDoc, and Doxygen all handle it fine. --bb
Jan 22 2008