August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Walter | "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. |
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Walter | 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 |
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Walter | >> 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 ;) ) |
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Derek Parnell | > 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 ;)
|
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Walter |
> /**
> * 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.
|
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to ElfQT | 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 |
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Ben Hinkle | "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>. |
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Derek Parnell | "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! |
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to ElfQT | "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> |
August 27, 2005 Re: Embedded Documentation in Comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Derek Parnell | "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. |
Copyright © 1999-2021 by the D Language Foundation