New PHPDoc inspections and quick fixes

There is a number of new PHPDoc inspections available in the latest PhpStorm 2.1 EAP builds which allow to find basic problems in PHP code documenting. These new inspections can be turned on/off in Settings|Inspections|PHP|CodeStyle/PHPDoc. Traditionally each inspection has a quick fix increasing your productivity.

Missing PHPDoc comment

Finds elements (functions, classes, constants etc.) which do not have a PHPDoc comment. Note that the inspection is off by default. When turning it on you can also configure which elements must be documented depending on your code style requirements, see Settings|Inspections|PHP|CodeStyle|Missing PHPDoc Comment:

 

Here is an example of a function with missing PHPDoc comment and a quick fix menu invoked with Alt+Enter shortcut:

After selecting “Generate PHPDoc Comment” you instantly get the following:

Well, you still have to write comments to the function and its parameters but that’s what can’t be automated at the moment :-)

Note: in later PhpStorm releases the inspection settings will be moved to the same group with other PHPDoc inspections below: Settings|Inspections|PHP|PHPDoc.

Missing @return tag

The inspection checks that PHPDoc of a function (method) which may return some value doesn’t have an appropriate @return tag. Let’s assume that my setDisplayMode function returns either 0 or null. In this case the inspection will report “Missing @return tag…” for generated or manually written PHPDoc:

Invoking “Add @return tag” quick fix will add the tag to PHPDoc along with expected return type:

PHPDoc comment matches function/method signature

The inspection reports a problem if a number of parameters described in PHPDoc comment and/or their types do not match a corresponding function or method declaration.

Let’s change the previous example a bit by replacing $total parameter with $disp_option and assigning a default value of 0 to $disp_mode:

You will find that the inspection reports “PHPDoc comment does not match function or method signature”.

“Update PHPDoc Comment” quick fix will change the comment as follows:

Let’s see what has happened. First, $disp_option parameter has been added. Second, $total parameter is now under @internal tag which excludes it from generated documentation. Note that any comments you might have written for $total parameter are preserved as well as function comments.

Note also that “Update PHPDoc Comment” fix will generate a @return tag if it is missing.

Running PHPDoc inspections in batch mode

You can run PHPDoc inspections in batch mode  using Code|Inspect Code… Here is an example of PHPDoc inspections result for project files:

The described inspections can be a very good reminder to keep your code documentation up-to-date. And let’s be honest, that’s something we often forget to do :-)

This blog is permanently closed.

For up-to-date information please follow to corresponding WebStorm blog or PhpStorm blog.

 
This entry was posted in Cool Feature, PhpStorm and tagged , , . Bookmark the permalink.

9 Responses to New PHPDoc inspections and quick fixes

  1. SebCorbin says:

    Nice one ! I’ll finally have my function properly documented :)

  2. Chen says:

    The best idea ever.
    This will help to get all functions documented. Thanks. :)

  3. Crack says:

    Great feature, really helps with fixing docs in old code :)

  4. Morfi says:

    Add please PHPDoc for static magic methods (__callStatic)

  5. Vladimir Fishchenko says:

    Can you add something to a batch checking code with PHP_CodeSniffer?

  6. I’m not seeing the Generate PHPDot Block when i press control+return (on a mac). How do you get this to show up??

  7. Tim Hawkins says:

    I love the inspection facility on PhpStorm, buit one thing that drives me nuts about it is that it does not show me which file the issue relates to, i have to click on the issue listed and have the editor open the file, and then hover over the tab to see where the full path of the file.

    We have a code structure where the code has many 100′s subdirectories with the same file names in it, like base.php, factory.php, loader.php. Inspections are near useless because we cant tell which file the issue lies in, without going through the whole open, inspect on each listed issue. Its hard to prioritize work on key parts of the code.

    Can I suggest that the issue listing tree, places the project relative path for the file, and line number next to the issue listing, so we can see where the problem lies.

  8. Rustam Vishnyakov says:

    Please submit your bug reports and feature requests to http://youtrack.jetbrains.net. Other users may vote for your improvement suggestion and this will help us to prioritize the issues. Thank you!

  9. Henning says:

    Hi
    is would be nice to be able to customize the generated PHPDoc Template to add the author tag for example or this already possible?
    @Vladimir Fishchenko
    Checkout http://lucassouza1.posterous.com/phpstorm-and-codesniffer
    This helped me integrate CS in PHPStorm. Not as nice as a plugin but a good start.

Comments are closed.