Thread overview | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
August 27, 2005 Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
I've put up a strawman proposal for embedding documentation in comments at www.digitalmars.com/d/doc.html |
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Walter | On Sat, 27 Aug 2005 04:47:18 -0400, Walter <newshound@digitalmars.com> wrote:
> I've put up a strawman proposal for embedding documentation in comments at
> www.digitalmars.com/d/doc.html
Page not found.
|
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Vathix |
"Vathix" <chris@dprogramming.com> wrote in message news:op.sv5s10p1l2lsvj@esi...
> On Sat, 27 Aug 2005 04:47:18 -0400, Walter <newshound@digitalmars.com> wrote:
>
> > I've put up a strawman proposal for embedding documentation in comments
> > at
> > www.digitalmars.com/d/doc.html
>
> Page not found.
Oops. It's there now.
|
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Walter | On Sat, 27 Aug 2005 04:47:18 -0400, Walter <newshound@digitalmars.com> wrote:
> I've put up a strawman proposal for embedding documentation in comments at
> www.digitalmars.com/d/doc.html
Not bad. What I don't seem to like is the "Params:" alternate method of documenting a function's parameters. I don't like the idea of lining things up in order for it to be parsed correctly. It leads to tabs/spaces conflicts. How about prefixing the identifier with @ and it will continue until another @identifier or the end of the comment. People will still probably line them up, but using tabs and spaces however they please.
A suggestion I have is a way to document if a function should be used as a property and not a function. Perhaps "Property: get" / "Property: set", that way a documentation generator could group them and strip the () from the display to further discourage them from being used as functions.
|
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Walter | "Walter" <newshound@digitalmars.com> wrote in message news:depaee$fre$1@digitaldaemon.com... > I've put up a strawman proposal for embedding documentation in comments at www.digitalmars.com/d/doc.html Nice. Some thoughts: - how about also having a License: section or something for any legal stuff that users need to know about. - allowing a wiki markup instead of embedded html solves the problem of just how much html is supported by a given tool. I'm just thinking of italics, bold, bold-italics, list and numbered lists and maybe a few others that I can't think of now. like monospaced-fonts or code. - should the Code block be Example? I'm not sure what kind of code to put in Code. |
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Vathix | "Vathix" <chris@dprogramming.com> wrote in message news:op.sv5uwjdol2lsvj@esi... > On Sat, 27 Aug 2005 04:47:18 -0400, Walter <newshound@digitalmars.com> wrote: > >> I've put up a strawman proposal for embedding documentation in comments >> at >> www.digitalmars.com/d/doc.html > > Not bad. What I don't seem to like is the "Params:" alternate method of documenting a function's parameters. I don't like the idea of lining things up in order for it to be parsed correctly. It leads to tabs/spaces conflicts. How about prefixing the identifier with @ and it will continue until another @identifier or the end of the comment. People will still probably line them up, but using tabs and spaces however they please. It's true that spacing is an issue but @ symbols are ugly and I'm glad Walter is avoiding them. How about "more leading whitespace than the previous line" means a continued param doc. > A suggestion I have is a way to document if a function should be used as a property and not a function. Perhaps "Property: get" / "Property: set", that way a documentation generator could group them and strip the () from the display to further discourage them from being used as functions. I agree properties should be special. Your idea of property get/set seems fine to me. |
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Ben Hinkle | On Sat, 27 Aug 2005 08:13:28 -0400, Ben Hinkle <ben.hinkle@gmail.com> wrote:
>
> "Vathix" <chris@dprogramming.com> wrote in message
> news:op.sv5uwjdol2lsvj@esi...
>> On Sat, 27 Aug 2005 04:47:18 -0400, Walter <newshound@digitalmars.com>
>> wrote:
>>
>>> I've put up a strawman proposal for embedding documentation in comments
>>> at
>>> www.digitalmars.com/d/doc.html
>>
>> Not bad. What I don't seem to like is the "Params:" alternate method of
>> documenting a function's parameters. I don't like the idea of lining
>> things up in order for it to be parsed correctly. It leads to tabs/spaces
>> conflicts. How about prefixing the identifier with @ and it will continue
>> until another @identifier or the end of the comment. People will still
>> probably line them up, but using tabs and spaces however they please.
>
> It's true that spacing is an issue but @ symbols are ugly and I'm glad
> Walter is avoiding them. How about "more leading whitespace than the
> previous line" means a continued param doc.
All right, but that suggests you have to keep on adding more and more whitespace for more lines, like
/** This is my function.
* Params:
* fp File pointer
* name File name and
* more. Some more
* can go here but
* you have to add
* more and more
* spaces.
*/
"more leading whitespace than the line containing the identifier" or similar seems better.
|
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Vathix |
"Vathix" <chris@dprogramming.com> wrote in message news:op.sv53g81jl2lsvj@esi...
> On Sat, 27 Aug 2005 08:13:28 -0400, Ben Hinkle <ben.hinkle@gmail.com> wrote:
>
>>
>> "Vathix" <chris@dprogramming.com> wrote in message news:op.sv5uwjdol2lsvj@esi...
>>> On Sat, 27 Aug 2005 04:47:18 -0400, Walter <newshound@digitalmars.com> wrote:
>>>
>>>> I've put up a strawman proposal for embedding documentation in comments
>>>> at
>>>> www.digitalmars.com/d/doc.html
>>>
>>> Not bad. What I don't seem to like is the "Params:" alternate method of
>>> documenting a function's parameters. I don't like the idea of lining
>>> things up in order for it to be parsed correctly. It leads to
>>> tabs/spaces
>>> conflicts. How about prefixing the identifier with @ and it will
>>> continue
>>> until another @identifier or the end of the comment. People will still
>>> probably line them up, but using tabs and spaces however they please.
>>
>> It's true that spacing is an issue but @ symbols are ugly and I'm glad Walter is avoiding them. How about "more leading whitespace than the previous line" means a continued param doc.
>
> All right, but that suggests you have to keep on adding more and more whitespace for more lines, like
>
> /** This is my function.
> * Params:
> * fp File pointer
> * name File name and
> * more. Some more
> * can go here but
> * you have to add
> * more and more
> * spaces.
> */
>
> "more leading whitespace than the line containing the identifier" or similar seems better.
whoops - good point :-)
|
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Walter | Excelent ideas. Are you planning on having the compiler produce the documentation itself? That would be killer!
Walter wrote:
> I've put up a strawman proposal for embedding documentation in comments at
> www.digitalmars.com/d/doc.html
>
>
|
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Walter | Walter wrote:
> I've put up a strawman proposal for embedding documentation in comments at
> www.digitalmars.com/d/doc.html
>
>
Nice ideas, and the code/doc looks pretty clean too.
One objection: the first form of param documentation looks ugly (to me):
void foo(
int x, // is for this
int y // is for that
)
And for the 'Deprecated', it seems redundant, the compiler already knows the function is deprecated.
I think the only thing to document about a deprecated function is why it's deprecated, and what should we use instead of it.
/**
Use bar() instead
*/
deprecated void foo() { ... }
Embedded HTML doesn't look very good :/
|
Copyright © 1999-2021 by the D Language Foundation