Documentation is a required component for any long-term software application that has developers coming and going, or generally an expanding team. You won’t just have to explain code to new developers, but also to yourself and your current developers when they look back at what they did even just a month ago.
The hardest part is maintaining documentation as your code changes. Often documentation can become outdated, yet it will still be there and you’ll be looking at it as if it explains the current code, i.e. the code has changed but the documentation has not kept up.
The way to solve this problem is to automate documentation generation based on code comments (i.e. generate documentation from code comments), and to follow standard documentation practices, i.e. “PHPDoc.” PHPDoc is the formal standard for commenting PHP code. It’s a simple syntax to comment classes and their methods. So if you keep your comments up to date for just your classes and methods, you’ll be good to go because of the following tool I’m about to describe that will automatically generate a mini-site of documentation based on those comments.
To use it enter the following commands from your Ubuntu command line:
# apt-get install doxygen
# apt-get install graphviz
# apt-get install mscgen
# doxygen -g
When you type doxygen -g it will generate a file in the current directory called “Doxyfile.” That file is a very large configuration file. You need to edit this file. Here you enter all sorts of options, but most importantly the directory where your code is. You do so by specifying a simple “input” directive, as explained here:
Then obviously you setup Apache to display this site on the internet, and boom you have a mini-site with all your documentation. Just re-run this command any time you want to update it, and it will update it. This site will list all your classes, methods, and interlink pages together nicely, even generate all sorts of UML diagrams. UML diagrams are diagrams explaining code. Learn about it: http://en.wikipedia.org/wiki/Unified_Modeling_Language . Otherwise, all your code comments will be in there as well associated with their corresponding method or class. You of course get several ways to browse your documentation pages: by class name, method name, searching, etc.
That all said, the Yii Framework itself has awesome documentation in its “class reference” on its site. It’s obviously automated as well, and they very possibly use Doxygen themselves, plus a few custom enhancements to the generate mini-site. I would love it if the contributors to the framework would share their code documentation tools as a feature of the framework itself so you could easily generate documentation of your Yii apps. I’ve been meaning to bring it up in their forum and probably will some time soon. If that ever comes out, forget Doxygen. Until then, Doxygen is our pick at FaceySpacey--and yes over PHP Documentor: http://www.phpdoc.org/ . We’ve used both extensively and Doxygen is a lot better. Doxygen also happens to support many languages besides PHP. You’d expect the one just for PHP to be better, but it isn’t.