"Walter" <newshound@digitalmars.com> wrote in message news:deqtkq$2aq0$2@digitaldaemon.com...
>
> "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".

Then can Params also become a verb like Takes or Needs or ... I dunno... Eats or something. It seems wierd that the other sections are nouns (well, except Include and Deprecated) but Returns is a verb. To me it clashes with Params most importantly.

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

sneaky :-)

On Sat, 27 Aug 2005 16:35:06 -0700, Walter wrote:

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

Just a little note, I used an 'e' deliberately so as to make 'Docter' more grep-able, but whatever!
-- 
Derek Parnell
Melbourne, Australia
28/08/2005 10:44:52 AM

Derek Parnell wrote:
> On Sat, 27 Aug 2005 16:35:06 -0700, Walter wrote:
> 
> 
>>"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.
> 
> 
> Just a little note, I used an 'e' deliberately so as to make 'Docter' more
> grep-able, but whatever!


I figured that your "Docter" spelling was intentional.  It fits together "doc" and "ter" like a modifier for a verb to make it a noun (almost like "fish-er" or "bat-ter".  It had an added humorous touch of sounding like "Doctor."

-JJR

"John C" <johnch_atms@hotmail.com> wrote in message news:deqq8l$28lg$1@digitaldaemon.com...
> 1) Will we be able to add custom sections?

Currently, unrecognized sections are just passed through to the output unchanged.

> 2) Can you add a "Property" section?

?

> 3) Will it recognise protection attributes?

Sure.

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

Right.

"John Reimer" <terminal.node@gmail.com> wrote in message news:der9mm$2iuj$1@digitaldaemon.com...
> Derek Parnell wrote:
> >>The neato thing is "Doctor" doesn't need to even exist before one starts using that style.
> > Just a little note, I used an 'e' deliberately so as to make 'Docter'
more
> > grep-able, but whatever!

Ok, I see that. But I'm concerned that people will fail to recognize that, leading to confusion. It's like I knew a person named Gregg once. He spent most of his life correcting other peoples' spelling of his name. Another fellow's last name was Hogg. He spent most of his life correcting other peoples' pronounciation of his name (he claimed it was pronounced "hoag").

> I figured that your "Docter" spelling was intentional.  It fits together "doc" and "ter" like a modifier for a verb to make it a noun (almost like "fish-er" or "bat-ter".  It had an added humorous touch of sounding like "Doctor."

"Docster" might work? On second thought, yuk.

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

One possible (albeit not beautiful) solution might be to allow braces in doc comments, in the same sense as attribute blocks:

# /// documentation for C
# /// {
# class C { }
# /// }
#
# class D { }

-- Chris Sauls

Walter wrote:
> 
> 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).
> 
But that is not the manual page. It is not the final doc output. And if we think it as such we might as well complain about those unnatural "/**  *  */  /// /++  +  +/",etc. symbols all over it.

>>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.
> 
See answer above. It already has lots of code symbols like "/**  *  */ /// /++  +  +/", possibly others. Not to mention the doc is placed interlaced with computer code (the D language itself). And I frankly I don't see any problem with that, when one wants to see a more cleaner doc, just see the generated output doc.
(I sense this issue won't go much far than being a matter of personal opinion/taste)

-- 
Bruno Medeiros
Computer Science/Engineering student

"Walter" <newshound@digitalmars.com> wrote in message news:deqtkr$2aq0$3@digitaldaemon.com...
>
> "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.

Since to me an empty doc comment isn't obvious it means "same as above" (to me it looks like someone forgot to say something) how about having a word there like Ditto (which means according to dictionary.com "same as stated above or before").

In article <derhht$2pm2$2@digitaldaemon.com>, Walter says...
>
>
>"John Reimer" <terminal.node@gmail.com> wrote in message news:der9mm$2iuj$1@digitaldaemon.com...
>> Derek Parnell wrote:
>> >>The neato thing is "Doctor" doesn't need to even exist before one starts using that style.
>> > Just a little note, I used an 'e' deliberately so as to make 'Docter'
>more
>> > grep-able, but whatever!
>
>Ok, I see that. But I'm concerned that people will fail to recognize that, leading to confusion. It's like I knew a person named Gregg once. He spent most of his life correcting other peoples' spelling of his name. Another fellow's last name was Hogg. He spent most of his life correcting other peoples' pronounciation of his name (he claimed it was pronounced "hoag").
>
>> I figured that your "Docter" spelling was intentional.  It fits together "doc" and "ter" like a modifier for a verb to make it a noun (almost like "fish-er" or "bat-ter".  It had an added humorous touch of sounding like "Doctor."
>
>"Docster" might work? On second thought, yuk.

or Docmeister
or Docinator

If it's built into DMD, I'm not sure we really need a special name for it. Couldn't we just call it D-style documentation.

jcc7

>> "Docster" might work? On second thought, yuk.
>
> or Docmeister
> or Docinator

Doculator
Docalicious
Doctastic
Cod
What's up Doc
DMDoc