Thread overview | |||||||||
---|---|---|---|---|---|---|---|---|---|
|
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 | ||||
---|---|---|---|---|
| ||||
Posted in reply to Unknown W. Brackets | "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 | ||||
---|---|---|---|---|
| ||||
Posted in reply to Unknown W. Brackets | 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 | ||||
---|---|---|---|---|
| ||||
Posted in reply to Jason House | 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 | ||||
---|---|---|---|---|
| ||||
Posted in reply to Bill Baxter | 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 | ||||
---|---|---|---|---|
| ||||
Posted in reply to torhu | 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 | ||||
---|---|---|---|---|
| ||||
Posted in reply to torhu | 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
|
Copyright © 1999-2021 by the D Language Foundation