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.
- 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.
Thanks for your great input!
PHP_Codesniffercan indicate when there is no docblock -- see the examples of reports on this page (quoting one of those) :
I suppose you could use PHP_Codesniffer to at least get a list of all files/classes/methods that don't have a documentation; from what I remember, it can generate XML as output, which would be easier to parse using some automated tool -- that could be the first step of some docblock-generator ;-)
Also, if you are using phpDocumentor to generate the documentation, can this one not report errors for missing blocks ?
After a couple of tests, it can -- for instance, running it on a class-file with not much documentation, with the
--undocumentedelementsoption, such as this :
Gives this in the middle of the output :
But, here, too, even if it's useful as a reporting tool, it's not that helpful when it comes to generating the missing docblocks...
Now, I don't know of any tool that will pre-generate the missing docblocks for you : I generally use PHP_Codesniffer and/or phpDocumentor in my continuous integration mecanism, it reports missing docblocks, and, then, each developper adds what is missing, from his IDE...
... Which works pretty fine : there is generally not more than a couple of missing docblocks every day, so the task can be done by hand (and Eclipse PDT provides a feature to pre-generate the docblock for a method, when you are editing a specific file/method).
Appart from that, I don't really know any fully-automated tool to generate docblocks... But I'm pretty sure we could manage to create an interesting tool, using either :
token_get_allto parse the source of a PHP file.
After a bit more searching, though, I found this blog-post (it's in french -- maybe some people here will be able to understand) : Ajout automatique de Tags phpDoc à l'aide de PHP_Beautifier.
Possible translation of the title : "Automatically adding phpDoc tags, using PHP_Beautifier"
The idea is actually not bad :
PHP_Beautifiertool is pretty nice and powerful, when it comes to formating some PHP code that's not well formated
PHP_Beautifier_Filterfor a list of provided filters
The idea that's used in the blog-post I linked to is to :
To run the tool on some
MyClass.phpfile, I've had to first install
Then, download the filter to the directory I was working in (could have put it in the default directory, of course) :
And, after that, I created a new
beautifier-1.phpscript (Based on what's proposed in the blog-post I linked to, once again), which will :
phpDocfilter we just downloaded
The code of the
beautifier-1.phpscript will like this :
(Once again, the biggest part is a copy-paste from the blog-post ; I only translated the comments, and changed a couple of small things)
Note that I also had to path two small things in
phpDoc.filter.php, to avoid a warning and a notice...
The corresponding patch can be downloaded there : http://extern.pascal-martin.fr/so/phpDoc.filter-pmn.patch
Now, if we run that
MyClass.phpfile that initialy contains this code :
Here's the kind of result we get -- once our file is Beautified :
We can note :
doSomethingwas already present in our code : it's not been removed.
Now, it's not perfect, of course :
But I'm pretty sure that this idea could be used as a starting point to something a lot more interesting :