Cover image for post Documentation in a nutshell

Documentation in a nutshell

What is one of the most important things a developer (and of cause everyone else in IT business) has to do and the worst thing he can imagine to do, at the same time? Correct: Writing documentation.

Documentation for PEAR projects has been allways been a pain for us developers. Most of use mainly inline documentation to provide a minimum amount of docs to other developers and to freshen up their mind from time to time. The original PEAR documentation standard (peardoc2, based on DocBook XML) is even used more rarely, because the format is quite complex and it's a pain to write documentation. And, most important: You have to do documentation twice.

So, what's the way, to make developers more happy with documentation? A way to avoid double documentation effort. A way to avoid crappy DocBook debugging sessions. A way to keep documentation actual. And this way is quite easy now!

phpDocumentor (which was initially a clone of JavaDoc) enables you to reuse your inline documentation for peardoc2 generation. The provided renderers can output template based HTML, CHM, PDF and XML documents and the standard installation (avalable through the PEAR installer: "pear install phpdocumentor") provides templates for docbook2.

Everything you have to do is to keep you inline documentation actual and phpDocumentor conform. A pretty simple console call will automatically generate peardoc2 files, which you only have to add to CVS. And the best: From the same sources, you can build up you personla HTML docs (maybe including private elements), downloadable PDFs or even comfortable CHMs.

Take a look. For Image_Text I use the following console call to generate peardoc2:

phpdoc -d ./ -i example.php,generate_package_xml.php,*.xml -it todo -t docbook/ -o XML: DocBook/peardoc2 -s -p -dc images -dn Image_Text

An example of Image_Text docbook generated HTML output is available on my development maschine, until sunday. This docs are generated from the actual Image_Text sources version 0.4.

That's all. :)

Since I commited the docs to the peardoc CVS module yesterday this will be up on pearweb on sunday (generation of peardoc HTML output is pretty expensive and for that run only once a week). But until then you can take a look here.

A pretty similar statement is used to generate my own HTML documentation, which includes private class elements. Just use the following command to create pure and nice looking HTML docs:

phpdoc -d ./ -i docbook/ dochtml/ generate_package_xml.php make_* package.xml CVS/ -t dochtml/ -o HTML:frames:phpedit -s -p -dc images -dn Image_Text

I guess, phpDocumentor is not the thing in life to solve all of your problems (as we all should know yet, this is XML* ;) ), but it can make your life a great bunch easier and more comfortable.

Beware that the peardoc2 generation of phpDocumentor has still some open issues (eg. peardoc2 can't use the "@todo" tag), but simple workarounds will help you to generate actual documentation pretty quickly.

For all who just want to give it a test: The batches I use for doc generation are available on CVS and inside the latest Image_Text package.