Auto-Commenting Tool

Question

Hello All,

I recently created a CMS for the client which is meant to work out of the box. But I made a mistake by not commenting my code at the time of writing. Just wanted to know if there is a tool that will go through the files of CMS and add comment blocks automatically.

Let's suppose I have this code:

class foo{
  function bar(array $array){
    print_r ($array);
  }
}

The tool should be able to comment it like (or somewhat similar):

class foo{

/**
 * bar
 *
 * @access  public
 * @param   array
 * @return  void
 */
 function bar(array $array){
  print_r ($array);
 }

}

Edit:

The tool should only add phpdoc stubs, i will write explanatory comments myself.

Answer 1

While I am sure there is tools that can reflect on the signature (and to a lesser extent tokenize the method body), I am pretty sure there is no tool that would be able to insert the short or long description of the method. Think about it, that's where you - the developer - describes what the function is supposed to do.

So even if there is a tool that can insert the stubs, you will have to go through each comment anyway. And in this case, you can just as well use an IDE like Zend Studio, Eclipse with PDT or Netbeans to insert the comment blocks. They will insert the stubs when opening a new comment block automatically, so all you have to do is fill in the description.

Answer 2

Comments are only useful if they add something that's not in the code. Of course there are tools that could add phpdoc like your example, but without manual effort, they won't add any value at all. Writing good comments is almost as hard as writing good code, maybe even harder; in fact, good comments (along with concise naming and proper consistent indentation) often distinguish good maintainable code from useless garbage.

You just didn't do your homework when you should have, so now you have to do it all at once. This means you'll have to manually step through your code and add comments yourself; a good IDE will be a great help for this (e.g. Netbeans can automatically generate phpdoc stubs for you), but the actual comment is up to you.

Answer 3

I had a little tool which transformed my ugly comment style into phpDoc blocks. In retrospect it's coded ugly, would run it carefully on other code (depends on C indendation style), and I don't even remember why it's called crw anyway. However it adds some @param boilerplate, and guesses parameter types from a few common variable names. So no substitute for manual post-editing.

Btw, I've always wondered why phpDoc doesn't have something like @output. The above example function is a void, so wouldn't it make sense to document that it prints something out?