You’ve heard it before but it’s worth mentioning again - you have to properly document you code! Programmers realized this back in the 1960s when the first industrial programming languages were defined, they came up with something called “comment lines”. For 27 years this was apparently considered enough, but in 1993 the first documentation generator was created by Eric Artzt, called Autoduck. Two years later, in 1995, a more commonly known documentation generator was released by Sun Microsystems, called Javadoc. In the year 2000 a similar generator was created by Joshua Eichorn for PHP, called the phpDocumentor and it’s this documentation generator that is the reason why I’m writing this post.
I’ve been using phpDocumentor for quite some time now but only to parse my classes to get an overview. Now I’m building a framework. I soon realized that writing a tutorial for each class wasn’t what I wanted. It’s always good with examples but it doesn’t show how a bunch of classes work together to solve a larger problem. I want to collect all documentation in one place so it’s impractical to write tutorials stored in some other place. So, for the first time I decided I’d take a look at the possibility to use external documentation with phpDocumentor.
DocBook “provides a system for writing structured documents using SGML or XML”, as stated in the preface in the DocBook documentation. It’s used in development projects like PHP and KDE. Although the PEAR manual states that DocBook should be used, nothing is said about the document type and no example is given. Instead, I found an short example in the phpDocumentor quickstart document. A more elementary example than that is hard to find, but if you combine that with the documentation about how you create a reference page in the DocBook documentation you’ll understand what you are doing. You don’t have to use the <refentry> top-level element but it is recommended if your code may become part of PEAR.
Since the phpDocumentor parses the DocBook file you can use some of the phpDocumentor syntax in your external documentation. It’s mainly two tags that you’ll use in your external documentation, and that’s the {@id} and {@toc} tags. The {@link} may also be useful to link between documents. There’s no need for me to dig any deeper in this, you can read a great tutorial about how to write tutorials for PHP at the phpDocumentor site.
Good luck!