Features PhpStorm

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 🙂

Comments below can no longer be edited.

9 Responses to New PHPDoc inspections and quick fixes

  1. Avatar

    SebCorbin says:

    May 10, 2011

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

  2. Avatar

    Chen says:

    May 10, 2011

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

  3. Avatar

    Crack says:

    May 10, 2011

    Great feature, really helps with fixing docs in old code 🙂

  4. Avatar

    Morfi says:

    May 12, 2011

    Add please PHPDoc for static magic methods (__callStatic)

  5. Avatar

    Vladimir Fishchenko says:

    May 15, 2011

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

  6. Avatar

    Jon Whitcraft says:

    May 19, 2011

    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. Avatar

    Tim Hawkins says:

    May 19, 2011

    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. Avatar

    Rustam Vishnyakov says:

    May 23, 2011

    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. Avatar

    Henning says:

    November 18, 2011

    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.

Discover more