I've put up a strawman proposal for embedding documentation in comments at www.digitalmars.com/d/doc.html

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.

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

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.

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

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

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.

"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 :-)

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

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