A tool to aid completion of missing or incomplete source code documentation
- by Pekka
I have several finished, older PHP projects with a lot of includes that I would like to document in javadoc/phpDocumentor style.
While working through each file manually and being forced to do a code review alongside the documenting would be the best thing, I am, simply out of time constraints, interested in tools to help me automate the task as much as possible.
The tool I am thinking about would ideally have the following features:
Parse a PHP project tree and tell me where there are undocumented files, classes, and functions/methods (i.e. elements missing the appropriate docblock comment)
Provide a method to half-way easily add the missing docblocks by creating the empty structures and, ideally, opening the file in an editor (internal or external I don't care) so I can put in the description.
Optional:
Automatic recognition of parameter types, return values and such. But that's not really required.
The language in question is PHP, though I could imagine that a C/Java tool might be able to handle PHP files after some tweaking.
Looking forward to your suggestions!
Bounty
There are already very good suggestions for this (that I have not yet had the time to check out) to point out the gaps, but none yet providing aid in filling them. I want to give the question some more exposure, maybe there is some sort of a graphical extension to php_codesniffer to achieve the level of automation I'm dreaming of. Looking forward to any additional input!
