PHPADD: abandoned docblocks detector

Docblocks may become as evil as comments when they’re not treated as first-class citizens (see: Meaningless docblocks).

PHPADD can analyze a directory with PHP source code and detect (for each file, for each class, for each method) if the parameters in the function declaration are compatible with the parameters found in the docblock, reporting the outdated ones.

This can be easily integrated in your build script and the result can be published in build result. Using Hudson, you just need HTML Publisher plugin.

Install it
With PEAR it is very simple. On Linux, you may need to prefix each command with sudo.

pear channel-discover
pear install webmatters/phpadd

Try it
Once installed it responds to phpadd from your console.

phpadd --publish-html /tmp/output.html directory/to/analyze

This command will produce an output like this.

Please note, phpadd has to be improved. For example, it needs to ignore warning on files/classes/methods matching a given regular expression (controller classes, for example).
Or the difference between docblock params and function params: it is not so smart.
If you want to help, fork it on GitHub!

This entry was posted in PHPADD. Bookmark the permalink.

15 Responses to PHPADD: abandoned docblocks detector

  1. Excellent!! I will like to translate to spanish!! if you allow me 😀

    Best Regards!

  2. Good job :) It’s very helpful!

  3. Pingback: PHPADD | CodersGroup

  4. Filip says:

    This can be achieved also by Php Code Sniffer

    • fmntf says:

      Please correct me if I am wrong, but phpcs detects only missing docblocks, and not the outdated ones.

      • Danger-Lifter says:

        phpcs also detects invalid and not-actual names and types. ie:
        “Doc comment var “$helper” does not match actual variable name “$name” at position 2″

  5. Ektion says:

    Good work on this package. I am slightly curious if there will be any windows version of this?

  6. Pingback: Programowanie w PHP » Blog Archive » Francesco Montefoschi’s Blog: PHPADD: abandoned docblocks detector

  7. Peter Fisher says:

    This is great. Will defiantly look onto this more.

    A few questions
    1) What will the output be if the program doesn’t find any problems?

    2) Are we able to get a summary via the command line?
    EG ‘no errors found’ or ‘2 errors found’ .

    This would be handy if we were to integrate this program in a pre build checking process. The stdout would be used by the next checking program and would run based on this output.

    We could even go a step further and automatcally update the doc block based on a y/n interaction with the user.

    3) How easy is it to skin the html output?

  8. fmntf says:

    Hi Peter. Thank you for your interest.

    1) It depends on the publisher you use. Using HTML publisher you will get something like “Found 123 regular methods (100%) and 0 irregular methods (0%). Tab delimited text would produce an empty file.

    2) Not right now, but it can be easily implemented. An optional --summary switch would print “$n errors found”, while the full report is published in the standard way. It is also possible to associate a return codes to the shell:
    0 no errors
    1 invalid arguments (this is already implemented)
    2 mess found

    3) I didn’t need to style the output so right now the HTML and CSS is very, very basic and hardcoded. We should analyze what is needed. A simple first step could be to add hook CSS classes to the HTML and introduce --with-css my/project.css option. What do you need?

    2b) Regarding the automatic update of docblocks: it never thought that feature. It can be done, but it will be limited. There is no support for typehint of scalar arguments in PHP. And what about the text over the arguments? If the arguments are changed, the text may need some change too.

    Please tell me if what I’m supposing would be enough for you. Or, if you prefer, you can fork the project and issue a pull request!

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>