Re: Re: [PHP4BETA] Re: [PHP-PEAR] PEAR javadoc-style docs

Ulf, I also feel that POD is probably better suited to writing man pages and the like. I support your assessment that Javadoc would be best suited for rapid and reliable API documentation. The Javadoc style seems to me, better suited to the task of rapid and easy documentation as it has a much lower threshold of required knowledge than XML. Javadoc is simple and direct, yet powerful enough to get the job done. As long as it is applied consistently, I don't see any reason why we should not be able to parse the Javadoc and render in any of a number of convenient forms (including XML). Sean Borman On Fri, 12 May 2000, Ulf Wendel wrote: > > > Sterling Hughes wrote: > > > > Ulf Wendel wrote: > > > The best way of inline documentation to generate references is javadoc. > > > I prefer it over XML. If we would use XML we would have to develop a > > > DTD. If we use six, seven or maybe eight @something-"tags" we have some > > > very few, simple rules. These tags are very familiar to those who know > > > java and those who do not, will not have difficulties learning them. > > > > > > > What about POD. Its easy, well known, and proven to work (CPAN)? > > I must confess, I've never used it before. When I looked at an article > on POD I got the feeling that you're quite free in documenting the > source. There're no rules where to place certain comments are there? > > My intention is to be able to build a quick reference from the source of > a php script. So I introduce some general rules. Phpdoc comments are > only recognized when they are placed in front of one of the following > keywords: > > - var (instance/class variables) > - functions (methods) > - class > > Inline Documentation somewhere else in the source gets ignored. This way > you make clear that phpdoc is used to build a quick reference. It > can't be used to write a manual, a tutorial or any other kind of > documentation but a quick reference. > > POD seems to be different, right? POD allows you to write a manual and a > quick reference in one. I don't like this idea. A manual has no place in > the source... > > Phpdoc would have some, few "tags" that are essential to build a quick > reference such as @param, @return, @access and others. Phpdoc would > extract @param tags, compare it with the function definition and render > it always in the same way. With POD the documentation must not fit a > function definition and it can be freely formatted. > > No, I preferr using some kind of javadoc styled docs. > > Ulf > > -- > PHP Extension and Add-on Repository (PEAR) mailing list. > Documentation can be found at http://pear.php.net/doc/pear.html > To unsubscribe, e-mail: php-pear-unsubscribe@lists.php.net from the > mail address you subscribed with. > >