Source Code Documentation

Generating Documentation Using PHPDocumentor 2

I though I would write a little bit about how we document our source code at Chic Computer Consultants and give an example of how we setup our documentation website.

As we all know it is important to have up to date documents and we try to keep our as up to date as possible.

Inline Documentation

We use inline comments inside our source files to document our source code we use Phpdocumentor to generate a documentation website from these inline comments.

It is very simple and makes life a lot easier by automating the updating of our documents allowing us to just run it by cron and that is all we have to worry about.

You can add inline docs simply by using the following comments in you source files,

/**
* Comment Header
* <p>Some stuff here to describe our content</p>
* @package default
* @category core
*/

The above comment contains a paragraph and also defines the package directive this directive is used with @category to compartmentalise your source tree.

/** Another PHPDocumentor comment */

Above is a simple comment with no directives for a complete list of directives please see this page and for more information on using Phpdocumentor please see here.

Generating Documents

To generate the documentation we use PHPDocumentor 2 to transverse our source tree and parse the inline comments into a nice easy to use format which is web accessible for our web site we use digest authentication to restrict access to our documents.

Our first task was to install PHPDocumentor which is really simple to do as they use pear to package up their software.

root@chic:~# pear channel-discover pear.phpdoc.org

root@chic:~# pear install phpdoc/phpDocumentor-alpha

It should now be installed on your system under /usr/bin which should be in your $PATH allowing you to access the program by typing phpdoc at a shell prompt.

Once we had installed the software needed to generate our documentation we needed to modify the configuration file so we can change the title and heading to something more custom.

Vi Config

The file we need is the main configuration file for Phpdocumentor you could also create a custom one but the default suited our needs. There is more information in the docs here. So our next step is to use the following command,

root@chic:~# updatedb && locate phpdoc.tpl.xml

This command will update the slocate database then us slocate to try and find the config file but only if the previous command was successful. The file is named phpdoc.tpl.xml and on our system (Debian) it was located here,

/usr/share/php/phpDocumentor/data/phpdoc.tpl.xml

If you open up this file you can add a custom title which in our case we named it Chic Computer Consultants Documentation. You can use any editor we like vi or nano.

vi /usr/share/php/phpDocumentor/data/phpdoc.tpl.xml

Once in vi switch from command mode by pressing i and add the following line to the bottom of the file inside the <phpdocumentor> tags (file is an XML file) then exit vi saving the file (shift zz).

<title>Chic Computer Consultants Documentation</title>

After this we needed to setup a virtual host on Apache, configure the DNS to point towards our documentation website (docs.chic.uk.net) and install dependencies (this may vary on your system).

apt-get install php5-xsl graphviz graphviz-dev

Then finally we can generated the documentation we decided to use the default template which is responsive*.

phpdoc -d /path/to/web/root/source_tree/ -t /path/to/web/root/docs/

Once the program finishes running our documentation website has been created so its time to check it all worked and looks good.

We use cron to update our documentation every night but you need to add the -q switch to the end of the above command this will suppress any output.

Documentation Example

More Documents

We also have other types of documents to help us develop our software, we use Dia for creating diagrams of our database schema. We use a relational database (RDBMS) so we map our associations using it. You can also create other kinds of diagrams using Dia but that is beyond this article.

For our UML documents we like to use umbrello which we think is great for modelling our class hierarchy and creating class maps helping us keep track of whats doing what.

UML Diagram

For any word processor documents or spreadsheets we use Libra Office which is a fork of OO.org. We use a word processor sometimes when we need to document use cases and such things.

Conclusion

We hope this article gives you an idea of how we handle documenting our development and some of the tools we use to accomplish this.

As you can see from our list of documentation software all our needs are provided by free and/or open source software stacks. Basing our development entirely on an open stack suits us as a company.

On a side note progress on the care related news system is coming along well and we are currently integrating it into our social media accounts so we will be documenting this system in a future article.

We have implemented so far, the administration panel, news editor panel and the news article front end so it should not be long before we are providing news.

We would also like to get some news syndication if we can find any one interested in providing and/or using our service.

Appendix

* At the time of writing 2013-05-29