Re: phpdoc / docbook / PEAR

> Derick lately applied some patches to PHPDoc and he even rolled a beta > release, so the project does not seem to be completely dead ;). Does that also include DocBook support? I searched for the word "docbook" in my PEAR::PHPDoc checkout, but it was not found... > Once someone wrote that PHPDoc is superior to PHPDocumentor in some > areas (IIRC it was the parsing stuff) Hum, excited to hear this... > , so we should consider merging > both instead of kicking PHPDoc. Anyways, I think this decision is over > to the maintainers of both packages. It would be really nice to have one official package finally really documented, maintained and supported. Looking at http://cvs.php.net/cvs.php/pear/PHPDoc it's quite hard to decide who are the maintainers. At least it seems Ulf is not one of them... I see mostly Derick, TimmiG and James Cox... > We had some discussion here about using API documentation as enduser > documentation and we came to the conclusion that API documentation is > often not very well-suited for this task, because it describes > technical details about the package. End-users need lightning > guides, tutorials and easy to understand examples that tell them > how to use the package. This is absolutely true. BUT projects without correct developer documentation are subject to be maintained by an individual or even not at all. Developer documentation should contain conceptual details as well as API information. DocBook is ideal to write conceptual docs, and PHPDoc is designed to write API docs. The only problem with using these two is that you'll have two documentation for developers, so it's a natural need to have PHPDoc comments converted to DocBook, and so use the huge variety of tools to generate HTML/PDF/RTF/etc. This way you can have one documentation interlinked even between the conceptual and API parts. That is what a deceloper would love to see, and I'll definitely cover in my speech. ;) Goba