Vathix wrote:
> On Sat, 27 Aug 2005 08:13:28 -0400, Ben Hinkle <ben.hinkle@gmail.com>  wrote:
>> 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.


Why not simply use : or - after each parameter. I haven't thought about this too much, but this seems natural, looks good, and avoids ugly prefixes and the requirement for lining parameters up exactly. For example,

/** This is my function.
 * Params:
 *     fp:   File pointer
 *     name: File name
 */

or

/** This is my function.
 * Params:
 *     fp - File pointer
 *     name - File name
 */

Alternatively, you could view more then one parameter as a list of definitions, where list items are identified by the prefix - and the defined term is identified by the ending :. For example,

/** This is my function.
 * Params:
 *     - fp: File pointer
 *     - name: File name
 */

I suppose you wouldn't need the : after the parameter name since names don't contain spaces.

Jason

"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
>
Looks good, especially since this type of info helps people understand the code while they're reading it, and then poof you have  a ready to go manual.

Walter wrote:
> I've put up a strawman proposal for embedding documentation in comments at
> www.digitalmars.com/d/doc.html
> 
Speaking of which, and considering what Walter said on the other thread( "I only disagree with the form that C# and Javadoc take, as they are needlessly and excessively klunky." ), what is the problem with Javadoc? ? I too agree that C# doc style seems clunky, but Javadoc's seems pretty ok to me (and is mostly similiar to that proposal). Is it because just the @ symbol? (Ben Hinkle commented elsewhere on this thread that it was ugly) wth.. what's so ugly about the AT symbol? :o

-- 
Bruno Medeiros
Computer Science/Engineering student

> That would be killer!
Yea it would.


"J Thomas" <jtd514@ameritech.net> wrote in message news:depov4$pqd$1@digitaldaemon.com...
> 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
> >
> >

[snip]
> (and is mostly similiar to that proposal). Is it because just the @ symbol? (Ben Hinkle commented elsewhere on this thread that it was ugly) wth.. what's so ugly about the AT symbol? :o

@because @human-readable @text @doesn't @have @ats @in @it

In article <deq7p5$1o63$1@digitaldaemon.com>, Ben Hinkle says...
>
>[snip]
>> (and is mostly similiar to that proposal). Is it because just the @ symbol? (Ben Hinkle commented elsewhere on this thread that it was ugly) wth.. what's so ugly about the AT symbol? :o
>
>@because @human-readable @text @doesn't @have @ats @in @it
>

It was mentioned that identifiers would automatically be emphasized.  I'm wondering if that would get annoying if you had a class member named 'a' or some other common english term that you'd use in your docs...  I think a special marker character should be used to deliniate identifiers from regular documentation.  It doesn't have to be @.  How about placing parens or curlies around it?

/**
* Remarks:  When using (myMember), don't forget to check for null!
*/

Regards,
James Dunne

In article <deq7p5$1o63$1@digitaldaemon.com>, Ben Hinkle says...
>
>[snip]
>> (and is mostly similiar to that proposal). Is it because just the @ symbol? (Ben Hinkle commented elsewhere on this thread that it was ugly) wth.. what's so ugly about the AT symbol? :o
>
>@because @human-readable @text @doesn't @have @ats @in @it
>

What? Could you repeat that <g>

"Vathix" <chris@dprogramming.com> wrote in message news:op.sv5uwjdol2lsvj@esi...
> 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.

I see your point, but I don't like the @ business because it doesn't look
like something someone would naturally write. An alternative that might work
is looking for:
    name=value
syntax.

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

"Ben Hinkle" <ben.hinkle@gmail.com> wrote in message news:depkh8$n10$1@digitaldaemon.com...
> "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.

That's a good idea.

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

There's always someone who's going to want to use the full capability of html. It's also easier to support in the documentation extractor - any html is just echo'd to the output.

> - should the Code block be Example? I'm not sure what kind of code to put
in
> Code.

It would be D code going in code blocks. I thought of calling it example:, but examples often contain much more than just code.

"J Thomas" <jtd514@ameritech.net> wrote in message news:depov4$pqd$1@digitaldaemon.com...
> Excelent ideas. Are you planning on having the compiler produce the documentation itself? That would be killer!

Yes, since the power of a default documentation system that is installed on every D user's machine is overwhelming. It'll produce a strong incentive to use it, thereby homogenizing the look/feel of documentation. It's the same reason why debug is in the language rather than a convention.

The ubiquity of javadoc for java code is a case in point - contrasted with the various incompatible competing schemes for C++.