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.
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.
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.