I’ve recently been going over a load of our applications to improve the quality and standards of our documentation. While we’ve mostly always had inline comments in code, the quality of those comments has varied a lot and we’ve had no central documentation resources.
For PHP there are plenty of documentation generators , phpdoc and doxygen being probably the leading examples. We had tinkered a bit with doxygen in the past so it wasn’t a big decision to standardise on that.
While most of our applications are php based there are some (like our google maps application) that are almost entirely written in javascript. Other applications have javascript files that augment the application.
Documenting just PHP would therefore only tell half the story – we needed something similar to doxygen for javascript.
Considering how extensively and widespread javascript has become over the past few years as the de facto standard in rich web applications I was surprised at how little tools there were for generating documentation. The ones I’ve managed to find are:
jsdoc initially seemed straight forward, but on running it against certain files it would always fail with a segmentation fault. Since it’s no longer maintained, it seemed a bit of a dead end unfortunetly
yuidoc seemed promising – it’s used in house at yahoo to generate documentation for their yui api. It’s a python based application though and has a lot of dependencies. I tried, and failed to get this working on my local machine. Wouldn’t have been practical to get running on our central server so that anyone in the team could use it.
pdoc – similar to above, but this time based on ruby. again wouldn’t have been practical to get running on our central server so that anyone in the team could use it.
jsdoc-toolkit – this was finally the one I settled on. It’s only requirement is java which is available on the central server and it produces nice documentation – especially when alternative templates like codeview are available for it.
The only problem I have with jsdoc -toolkit is that it’s very much geared to javascript api’s, and as such will by default only produce documentation for public functions. For API’s this is obviously fine, but if you want to have every funtion documented like we do then you have to jump through a few hoops when commenting and put explicit
*@name
*@function
*@description
tags into the comments of internal functions – that way the parser will pick them up correctly.
So there we go, apologies if this was long and technical, but I thought I would share the research in case it’s of use to anyone else.
Similarly, if anyone has suggestions for different alternatives that I’ve failed to find then I’d be interested in evaluating them, even if we are all in all happy with the solutions we’ve settled on.