RE: [PEAR-DEV] PHPod documentation

> DocPod sounds like a very good idea. I think we should try still going > through DocBook since it has been a success recipe for the PHP Manual > for years. > > The idea behind POD is very appealing, I think it's better than Javadoc > because of its no-nonsense approach. Also, with our current use of > Javadoc it's not clear what markup is allowed, but this is actually > defined in POD. > > How does everyone feel about maybe replacing Javadoc with something like > "DocPHPOD" for PEAR? I wasn't suggesting we replace phpdoc/javadoc, although that could be an idea I guess. My thinking was rather than documenting functions/classes a la javadoc style, the pod documentation would actuially serve as documenting the module itself. e.g. usage examples, general documentation, gotchas etc. Take for example Thomas' DB docs. A cut down example could be added to DB to make the module self documenting. Besides, pod is better suted to longer stretches of text AFAIK not little snippets for functions like javadoc. I think javadoc is still good though as it is more suitable for documenting parameters and return values for functions and I can't see why they can't sit side by side as they serve two essentially different purposes. pod = PEAR user javadoc = PEAR developer Cheers, Graeme