Re: Online doc generator (Was: Re: [PEAR-DEV] Amsterdam meeting agenda)

From: "David Costa" <gurugeek@php.net> > The problem is authors, not the format. PHPDocumentor has an excellent > GUI where every lead can produce some > basic XML documents. Once again, in my humble opinion the problem is > not the tool but the limited number of volunteers willing to > spend time with docs. This would not be a problem if every lead would > do some basic docs for his own package. Right... And there's not connection between a difficult format and few authors... I sure buy that... Come on, I'd have my packages well documented _if_ there was an easier way to do it (forget plain text). I started fooling around with Docbook and gave up. The phpDocumentor generation solution may be interesting, but last time I tried it, it didn't properly include inherited methods. Some packages like HTML_Common have no purpose of their own -- they are merely extended. And that kind of package needs not public documentation (besides API for developers). All inherited methods should be _automatically_ included, if phpDocumentor is supposed to be a good solution. Right now it's helpful, but not more than that. And anyway, there should be a simple --peardoc flag that sets all the proper formatting, so that generating documentation is as easy as "phpdoc --peardoc ./installroot package". Paul's right: we need to look at the requirements. I don't care if Docbook fulfills all of them -- we can't be like the sheep in Animal Farm who simply repeated whatever they were told. Klaus