New PHPDoc inspections and quick fixes

rustam.vishnyakov

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 :-)