• Unknown W. Brackets (23/23) Jan 20 2008 I'm a fan of the C# style of documentation comments, that is like this:
• Jarrett Billingsley (3/18) Jan 21 2008 I think it's just a bug.
• Jason House (6/12) Jan 22 2008 I've switched to using
• Bill Baxter (10/24) Jan 22 2008 I really prefer things like
• torhu (4/13) Jan 22 2008 I think this works, tango uses it:
• Bill Baxter (5/20) Jan 22 2008 Right. That's the *only* typical "big block" comment style that works.
• Bill Baxter (5/20) Jan 22 2008 DMD is the only documentation generator I know of that *can't* handle

"Unknown W. Brackets" <unknown simplemachines.org> writes:

/// 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]

"Jarrett Billingsley" <kb3ctd2 yahoo.com> writes:

"Unknown W. Brackets" <unknown simplemachines.org> wrote in message 
news:fn1jah$2nkh$1 digitalmars.com...


 /// 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. 

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.

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

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:

/********************************

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

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