Giving back to the community

So I finally did it, I made a blog.  I think it is finally time for me to blog about my ups and downs in the world of a php developer.  I hope to give back to some people out there some of the help I have received over the last decade of my life in forums, chat rooms and blogs.  So let's begin with my current ordeal.

I have been working on collegiateaccess.net for quite a while now.  None of the application source code is documented though.  They have 20+ year software vet reviewing the code that is having trouble with understanding it.  I have been tasked with documenting the entire project, along with the framework that was erected for it.  I have chosen phpDocumentor for the task.

Ironically enough, I have run into some documentation problems with the tool.  I have not been able to find a definitive resource on how to build the INI configuration file it uses.  Somehow, I must have skimmed over the documentation stating that this tool was to be run from the browser as well.  I learned rather quickly that once you fetch the PEAR package(I actually emerged it through Gentoo's marvelous portage), you must copy the phpDocumentor to a location on the web server you will be running it from.  I am actually running 3 folders in my project(trunk, documentation, phpdoc).  The phpdoc folder is copied from /usr/share/php/data/PhpDocumentor/ on my Gentoo system.  So from the project root:

cp -R /usr/share/php/data/PhpDocumentor/* phpdoc/

On my testing bed, the project root is the web root for that domain, so the application is accessed 'domain/trunk/', the documentation 'domain/documentation/', and phpDocumentor at 'domain/phpdoc/'.  The next step that had to be taken to get phpDocumentor to produce some documentation was to build the ini file.  So make a file [project].ini in your phpdoc folder.  This is where I ran into a real dilemna, what to put in the ini file.  It is actually not that bad.

[ParseData]
title = [the title of this documentation]
hidden = false
defaultcategoryname = Documentation
defaultpackagename = [project]
target = /home/[user]/workspace/[project]/documentation/
filename = /home/[user]/workspace/[project]/trunk/index.php,/home/[user]/workspace/[project]/trunk/app/collegiate.php
directory = /home/[user]/workspace/[project]/trunk/includes/,/home/[user]/workspace/[project]/trunk/app/controllers/,/home/[user]/workspace/[project]/trunk/app/models
sourcecode = on
output = HTML:frames:DOM/default,PDF:default:default,CHM:default:default

Let's go through this.  The hidden=false line prevents hidden files from being displayed.  defaultcategoryname is not really used all that much to my limited knowledge.  defaultpackagename is the package that all files not being notated with a @package [name] tag will be set to.  target is the location where the documentation will be placed.  filename is a comma seperated list of files to parse.  directory is a comma seperated list of directories to parse.  sourcecode=on means that the source code will be visible in the documentation.  This option requires that php has the 'tokenizer' enabled at compile time.  Gentoo users should have php compiled with the 'tokenizer' use flag.  output is a comma seperated list of modes with which to generate the documentation.  This one seemed to be the prettiest HTML version to me, and I wanted the PDF and CHM.  Please note that the paths I have included may not be correct for your setup and the [user] and [project] strings should be replaced to correctly reflect your path.  Also, I am not sure why, but I had to use absolute paths.  Relative paths were causing lots of trouble for me.

Once you have your ini file, you just need to do 3 things before you can generate your documentation.  Set the working directory at the bottom of the web interface(domain/phpdoc) to the absolute path of your project.  Go to config and type the absolute path to your project(or the folder you placed the ini file in).  Click change to change your configuration directory.  Go back to the config section once the page refreshes and select your ini file from the drop-down.  Click go to generate your documentation.

I hope this helps someone, because I had more trouble with this than I feel like I should have had.