All~ I disagree.
I don't like Java that much (for many reasons), but I have nothing but respect for the massive amount of documentation that is easily accessible as a direct result of JavaDoc. I personnaly feel that it greatly helped java achieve the success it has. If all of parrot's module were that well documented and that easily accessible, it would be a great boon in recruiting followers. Also, localizing the code and the documentation allow programmer to keep updated documentation more easily. Furthermore, since the docs will be in the same files as the code, we can simply refuse to accept patches that do not update the infile documentation. Thus preventing the horribly problematic outdated documentation. I say all of these things as someone who is new to this project and doesn't know POD. If some of my statements here are in ignorant of the way things are, please correct me. As I said, I am new to this and am waiting with baited breath for this newbie start file. Matt > -----Original Message----- > From: Tanton Gibbs [mailto:[EMAIL PROTECTED]] > Sent: Wednesday, October 02, 2002 11:59 PM > To: Erik Lechak; Sean O'Rourke > Cc: perl6-internals > Subject: Re: Self documenting comments for parrot > > > I hate to say this, but I'm still in favor of POD. It has all of the > functionality required > and is the official commenting style of parrot and perl. I > personally find > POD distasteful, > but since it is the norm, then I think we should stick with it. > ----- Original Message ----- > From: "Erik Lechak" <[EMAIL PROTECTED]> > To: "Sean O'Rourke" <[EMAIL PROTECTED]> > Cc: "perl6-internals" <[EMAIL PROTECTED]> > Sent: Wednesday, October 02, 2002 11:59 PM > Subject: Re: Self documenting comments for parrot > > > > Sean O'Rourke wrote: > > > > >Have you had a chance to look at doxygen? It doesn't support Perl, but > > >Perl is on the todo list, and (at least a couple of years ago) its C++ > > >support was pretty impressive. > > > > > >http://www.stack.nl/~dimitri/doxygen/ > > > > > >/s > > > > > > > > > > > I'm looking at it right now. Thanks for the link. This is the first > > time I have heard of doxygen. By the way is this an RFC thing? Should > > this "concept" be submitted to someone other than this group? Who makes > > the call about what finds its way into perl err ... I mean parrot? I'm > > super new and am trying to learn the ropes. And I am trying to write a > > "getting started guide", so I am required to ask seemingly stupid > questions. > > > > If others want me to continue with this. The next step would be to > > throw away 90% of my code and parse the parrotdoc into true XML. Then > > that opens up parrotdoc to all the functionality of XML. > > > > The style that I submitted is more or less XML with a comment like > > syntax. I wanted to keep the commenting style simple. It only has a > > few rules: > > 1) Parrotdoc start at the first char of a line. > > 2) They need a #. or a *. in front to destinguish them. > > 3) The number of dots is the depth of the tag. > > 4) The tag is all caps after the dots. > > 5) A colon is a line continuation charater. (you only need one after > > the tag to turn it on) > > 6) A @ assigns the attribute to the Node of that depth > > 7) A continuation stops with another tag or attribute or just a #. or a > > *. . > > > > for example : > > in xml: > > > > <DOCUMENT title="ParrotDoc Sample" author="Erik Lechak"> > > <SECTION title="a sample section"> > > This is the text > > </SECTION> > > </DOCUMENT> > > > > in perl "parrotdoc" style: > > > > #.DOCUMENT ParrotDoc Sample > > #.@AUTHOR Erik Lechak > > #..SECTION a sample section > > #...TEXT This is the text > > > > in c "parrotdoc" style: > > /* > > *.DOCUMENT ParrotDoc Sample > > *.@AUTHOR Erik Lechak > > *..SECTION a sample section > > *...TEXT This is the text > > */ > > > > Sorry for the long answer to your short question, > > Erik Lechak > > > > > > >
