Re: PHPod documentation

Alexander Merz wrote: > > > How does everyone feel about maybe replacing Javadoc with something like > > "DocPHPOD" for PEAR? > > PHPDoc is good for API-Documention, it shows dependencies between the classes > etc.. > PHPod would be seen technical, a bad replace for it. But, it could out-play its > advantage however within tutorial similar areas. > > Take a look at a perl-package, you often see examples and explanations on the > top followed by the source. But, the API-Doc is also in this part, separated > from the source. > > So we should combine PHPod and PHPDoc. > PHPod - for explanations and examples at the top of the srcfile > PHPDoc - for the API-Doc As every Pear package have its own directory my recomendation is to include a subdir called for ex: docs, where authors store the API-Doc generated from sources and put the documentation/examples. Having too much "literature" inside the code makes it harder to maintain for developers. It could be great to standarize the format of the documentation, but I prefer to see a simple.txt than a non-existant powerfull_docbook.xml :) Now for example in my tutorial only use six or seven HTML tags (<p>, <h*>, <code>, <hr>, <b>,...), so port it to others formats seems to be easy. But my problem with other formats is the fact that they don't highlight the php code, and IMO documents about php loose a lot without it. Perhaps a DocBook guru can say if it's posible to change the <programlisting role="php"> tag to do highlights (at least in the HTML output). Also the PHP manual itself could gain a lot with it. Tomas V.V.Cox