Ben Hinkle wrote:
> 
> I was using "dramatic license" to make my point. For a more serious answer look around you in the real world at forms containing information like application forms  or bills and you'll see stuff like
> 
>   address: 7 blah blah St
>   phone: 123-456-7890
>   account number: 1
> 
> Using : is a standard clue to humans. Using @ is great for computers but isn't natural for humans.
> 
The following seems to me much more natural(better word: readable) :

/**
 * Returns an Image object that can then be painted on the screen.
 * The url argument must specify an absolute {@link URL}. The name
 * argument is a specifier that is relative to the url argument.
 *
 * @param  url  an absolute URL giving the base location of the image
 * @param  name the location of the image, relative to the url argument
 * @return      the image at the specified URL
 * @see         Image
 */

than the equivalent in D proposal:

/**
 * Returns an Image object that can then be painted on the screen.
 * The url argument must specify an absolute {@link URL}. The name
 * argument is a specifier that is relative to the url argument.
 *
 * Params:
 * 	url   an absolute URL giving the base location of the image
 * 	name  the location of the image, relative to the url argument
 * return:    the image at the specified URL
 * see:       Image
 */

The "@" stands out much better. Explained in longer words:

I was going to say that we, as coders, are quite capable of dealing with that. But actually I think that any non-coder human would just as easily understand "@" as ":" , if explained the meaning. We humans are inefficient at processing obfuscated or large amounts of information. "@" is neither larger or more obfuscated than ":".
You may prefer ":" because in human language it already has a meaning similiar to what we want as a code keyword (or keysymbol), and thus you say it is more natural. But it doesn't we mean we wouldn't adapt easily (or in fact *instantly*) to a different symbol.

Indeed, while before I didn't think it made a difference (I was just considering compatibility with existing standards), now that you made me think about it, I do prefer "@" for the exact same reason you mentioned: that ":" already has a meaning in human language! And so one uses "@" for meta-language purposes because that's what the symbol will do (specifying "sections" as Walter called it), and ":" for proper human-language. Otherwise if one uses ":" as a keysymbol, one cannot use it in the human-language part (i.e. item description) or at least will have limitations, and/or confusion when using it.

-- 
Bruno Medeiros
Computer Science/Engineering student

<jmjmak@utu.invalid.fi> wrote in message news:deqirp$21vn$1@digitaldaemon.com...
> Speaking of javadoc, I hope we're not reinventing the wheel here. Both
javadoc
> and doxygen use a well known documentation syntax. Doxygen even supports d
(not
> completely though) already. I really hope a working doxygen support is everything we ever need.

This scheme will not impede anyone's use of Doxygen or a javadoc clone.

javadoc is pretty good, though it has some disadvantages:

1) Unnecessary overreliance on HTML. You need to use <p>, <code> ... </code> tags, etc., for basic use. I don't think <p> is necessary to separate paragraphs - why not a blank line? This will make it difficult to target something other than HTML with the documentation extractor.

2) Unnecessary use of @. Already discussed elsewhere.

"Mike Parker" <aldacron71@yahoo.com> wrote in message news:deqfvm$1upi$1@digitaldaemon.com...
> Ben Hinkle wrote:
>
>>
>> Using : is a standard clue to humans. Using @ is great for computers but isn't natural for humans.
>>
>>
> But on the other hand, once you've worked with Java for a while the @ symbols don't bother you at all. In fact, they stand out when perusing the source and pull your eyes to the important parts of the documentation. Not that I'm saying we should have them in D, but they really aren't all bad.

heh - I've never really liked how Javadoc looks. :-)
Even all the @params and @return bug me since most of the time the meaning
is obvious, especially with Java's recommendation for long descriptive
names. For example

 /** Adds two integers and wraps on overflow.
  * @param x the first integer to add
  * @param y the second integer to add
  * @return the sum of x and y
  */
 int add(int x, int y)

like, duh.

"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

Incredible!
I've left with only two arguments:
- Don't let two kind of parameter commenting. That will lead to confusion,
or not, itt will be harder to switch between reading style one and style
two.
I vote for the "header" style versus after each parameters, because there is
also a return value to comment, and don't need to linebreaks at the
parameters,

- the second: "all subsequent declarations at the same scope until another
documentation comment at that scope is found"
/// documentation for C and D
class C { }

class D { }

From that you can't tell if class D is documented for real, or just been
forgotten. That's a problem because compiler should falsely use the comment
for subsequent undocumented class, and because then the compiler cannot
require (generate warning/error) comment.
(In business app dev. I always require my team to use the c# compiler with
settings to signal errors on everything - on missing comment blocks also.
That's the first circle of defense with
unexperienced/lazy/forgetful/outsider coders.)
Also consider this:
Coder X writes:
/// documentation for C and D
class C { }

class D { }

Coder Y comes and continues the code with an overload of C:
/// documentation for C and D
class C { }

/// I've just inserted this little function
class C { int i }

class D { }

I don't see other way to resolve this, only to drop the referring to subsequent declarations - it is possible with referring unambiguously, but then you have to include something to refer to, and then refer to that later - that's too much and probably you'd fund it clumsy ;)

ElfQT

Walter wrote:
> 
> Using a postfix : isn't any harder for computers, so the argument for @ just
> falls away.
> 
What argument about being easier or harder for computers? No one was saying that. (it makes no difference for them computers, obviously)

-- 
Bruno Medeiros
Computer Science/Engineering student

"Bruno Medeiros" <daiphoenixNO@SPAMlycos.com> wrote in message news:deqm53$252u$1@digitaldaemon.com...
> The following seems to me much more natural(better word: readable) :
>
> /**
>   * Returns an Image object that can then be painted on the screen.
>   * The url argument must specify an absolute {@link URL}. The name
>   * argument is a specifier that is relative to the url argument.
>   *
>   * @param  url  an absolute URL giving the base location of the image
>   * @param  name the location of the image, relative to the url argument
>   * @return      the image at the specified URL
>   * @see         Image
>   */
>
> than the equivalent in D proposal:

I'd write it as this (with the caveat that it won't look quite right using a
proportional font):

/**
  * Returns an Image object that can then be painted on the screen.
  *
  * The url argument must specify an absolute URL. The name
  * argument is a specifier that is relative to the url argument.
  *
  * Params:
  *     url        an absolute URL giving the base location of the image
  *     name    the location of the image, relative to the url argument
  *
  * Returns:
  *                 the image at the specified URL
  * See:
  *                Image
  */

It already looks like a typical manual page. I've never seen a manual page that used @'s for emphasis (or any book printed since Gutenberg, for that matter).


> And so one uses "@"
> for meta-language purposes because that's what the symbol will do
> (specifying "sections" as Walter called it), and ":" for proper
> human-language.

A big goal for Ddoc (for lack of a better term!) is to have it look right in a proper human-language. I don't want it to look like computer code.


> Otherwise if one uses ":" as a keysymbol, one cannot use
> it in the human-language part (i.e. item description) or at least will
> have limitations, and/or confusion when using it.

Yes, that can be an issue, but I think it is very minimal. Section keywords must be the first non-whitespace on a line, and they must be immediately followed by the ':'. This means that a ':' in any other context is not significant. So, several workarounds are possible if this should occur (which I feel is unlikely):

1) put a space between the name and the ':'
2) put &nbsp; in front of the name
3) put <br> in front of the name
4) don't start that line with name:
5) use the &thinsp; character between the name and the ':'

etc.

"Ben Hinkle" <ben.hinkle@gmail.com> wrote in message news:deqmu5$25jg$1@digitaldaemon.com...
> heh - I've never really liked how Javadoc looks. :-)
> Even all the @params and @return bug me since most of the time the meaning
> is obvious, especially with Java's recommendation for long descriptive
> names. For example
>
>  /** Adds two integers and wraps on overflow.
>   * @param x the first integer to add
>   * @param y the second integer to add
>   * @return the sum of x and y
>   */
>  int add(int x, int y)
>
> like, duh.

I think I'll have Ddoc issue a fatal error message if any attempt is made to 'document' a return value of void. <g>

"ElfQT" <dethjunk@yahoo.com> wrote in message news:deqn6s$261i$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
> Incredible!

Thanks!

> I've left with only two arguments:
> - Don't let two kind of parameter commenting. That will lead to confusion,
> or not, itt will be harder to switch between reading style one and style
> two.
> I vote for the "header" style versus after each parameters, because there
is
> also a return value to comment, and don't need to linebreaks at the parameters,

I think you're probably right. I have seen the other style used in contexts where the programmers felt it to be a waste of keystrokes to type the parameter names redundantly more than once all over again.

> - the second: "all subsequent declarations at the same scope until another
> documentation comment at that scope is found"
> /// documentation for C and D
> class C { }
>
> class D { }
>
> From that you can't tell if class D is documented for real, or just been forgotten. That's a problem because compiler should falsely use the
comment
> for subsequent undocumented class, and because then the compiler cannot require (generate warning/error) comment.
[...]
> I don't see other way to resolve this, only to drop the referring to subsequent declarations - it is possible with referring unambiguously, but then you have to include something to refer to, and then refer to that later - that's too much and probably you'd fund it clumsy ;)

The reason I put it in like that is sometimes one documents as a group a set of related functions, such as:

    float sin(float)
    double sin(double)
    real sin(real)

and it's just feels stupid to have to separately document them with cut/paste. I understand the problem you're describing, though, and I don't see a solution to it other than "don't do that" :-(

> /**
>  * Returns an Image object that can then be painted on the screen.
>  * The url argument must specify an absolute {@link URL}. The name
>  * argument is a specifier that is relative to the url argument.
>  *
>  * @param  url  an absolute URL giving the base location of the image
>  * @param  name the location of the image, relative to the url argument
>  * @return      the image at the specified URL
>  * @see         Image
>  */

A trivial conversion of the above keeping the same layout but replacing @param with spaces and putting a "Params:" on top and substituting @return and @see as appropriate:

/**
  * Returns an Image object that can then be painted on the screen.
  * The url argument must specify an absolute {@link URL}. The name
  * argument is a specifier that is relative to the url argument.
  *
  * Params:
  *         url  an absolute URL giving the base location of the image
  *         name the location of the image, relative to the url argument
  * Return:      the image at the specified URL
  * See:         Image
  */

The version with the @s you have to look more carefully at the @params to parse them visually since at a glance they are very similar to the @return and @see. The D version is much easier for me to scan. If typing all the spaces in the params gets annoying I also think something like

/**
  * Returns an Image object that can then be painted on the screen.
  * The url argument must specify an absolute {@link URL}. The name
  * argument is a specifier that is relative to the url argument.
  *
  * Params:
  *   url    an absolute URL giving the base location of the image
  *   name   the location of the image, relative to the url argument
  *
  * Return:  the image at the specified URL
  * See:     Image
  */

looks ok. There are probably other readable variations on the spacing, too.

On Sat, 27 Aug 2005 01:47:18 -0700, Walter wrote:

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

Excellent start. Almost everything needed is in place. I'll give it a few more hours to sink in - maybe I'll start using it to see how it 'fits' before I comment much more.

-- 
Derek Parnell
Melbourne, Australia
28/08/2005 8:40:04 AM