View mode: basic / threaded / horizontal-split · Log in · Help
January 21, 2008
Documentation comments - /// feature request
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]
January 21, 2008
Re: Documentation comments - /// feature request
"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.
January 22, 2008
Re: Documentation comments - /// feature request
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.
January 22, 2008
Re: Documentation comments - /// feature request
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
January 22, 2008
Re: Documentation comments - /// feature request
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:

/********************************
January 22, 2008
Re: Documentation comments - /// feature request
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
January 23, 2008
Re: Documentation comments - /// feature request
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
Top | Discussion index | About this forum | D home