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

Lovely stuff so far. A few things:

1) Will we be able to add custom sections?
2) Can you add a "Property" section?
3) Will it recognise protection attributes?

A custom section could, for example, document what exceptions are thrown in a method.

Also, I wouldn't want private or package members to be visible in public documentation, or at least there should be a switch to turn such behaviour on and off.

On Sat, 27 Aug 2005 15:04:38 -0700, Walter wrote:


[snip]

> A big goal for Ddoc (for lack of a better term!)

Before the name is locked in, how about 'Docter' ;-)

-- 
Derek Parnell
Melbourne, Australia
28/08/2005 8:41:51 AM

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

Well, the editor should fill up the whole documentation space based on the
definition,
and then there's no double typing.
Writing:
int Foo(int a, int b)
then adding "///" above it should generate (as the latest doc spec. says):
/** !Add brief summary here!
 *
 * !Add a longer description if needed!
 * Params:
 * a:    !add description
 * b:    !add description
 */

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

Then make a "documentation reference" element:
/// Doc for sin
float sin(float)
/// See: float sin(float)

, or at least signal "continuining scope comment" with an empty
documentation:
/// Doc for sin
float sin(float)
///
double sin(double)
///
real sin(real)

(And in the second case, include a "compiler signals error on empty documentation" alongsidethe "compiler signals error on missing documentation" option for me ;) )

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

Wow, a lonely man, who puts practice before preach, experience before theory ;)

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

I now realize I typed "Return:" in my first post instead of "Returns:" (with an s). I don't know if I had Return because the Javadoc has @return or if I naturally removed the s because there is only one return value but probably many input parameters. In any case it's worth considering dropping the s from Returns.

ps- I use a monospaced font and the spacing looks messed up to me.

On Sun, 28 Aug 2005 00:52:35 +0200, ElfQT wrote:

>> 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.
> 
> Wow, a lonely man, who puts practice before preach, experience before theory ;)

Well, let's just say I carry a few 'battle scars'.
-- 
Derek Parnell
Melbourne, Australia
28/08/2005 9:11:41 AM

"Ben Hinkle" <ben.hinkle@gmail.com> wrote in message news:deqr6f$29a0$1@digitaldaemon.com...
>
> > /**
> >  * 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
> >  */
>
> I now realize I typed "Return:" in my first post instead of "Returns:"
(with
> an s). I don't know if I had Return because the Javadoc has @return or if
I
> naturally removed the s because there is only one return value but
probably
> many input parameters. In any case it's worth considering dropping the s from Returns.

I prefer "returns" because then it reads "returns the image at the specified URL".

> ps- I use a monospaced font and the spacing looks messed up to me.

That's because I composed it with a proportional font <g>.

"Derek Parnell" <derek@psych.ward> wrote in message news:leskatvqa7ub$.1gbohdes95d3h$.dlg@40tude.net...
> Before the name is locked in, how about 'Docter' ;-)

I like it!

"ElfQT" <dethjunk@yahoo.com> wrote in message news:deqqml$290d$1@digitaldaemon.com...
> , or at least signal "continuining scope comment" with an empty
> documentation:
> /// Doc for sin
> float sin(float)
> ///
> double sin(double)
> ///
> real sin(real)

That's not bad.

> (And in the second case, include a "compiler signals error on empty documentation" alongsidethe "compiler signals error on missing documentation" option for me ;) )

<g>

"Derek Parnell" <derek@psych.ward> wrote in message news:lehj9jkn6tik$.bapa4d70t2fb$.dlg@40tude.net...
> 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.

The neato thing is "Doctor" doesn't need to even exist before one starts using that style.