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]

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

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.

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

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:

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

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

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