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

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