PhpStorm 2018.3 Help

PHPDoc Comments

For documentation comments, PhpStorm provides completion that is enabled by default. PhpStorm creates stubs of PHPDoc blocks when you type the /** opening tag and press Enter, or press Alt+Insert and appoint the code construct (a class, a method, a function, and so on) to document. Depending on your choice, PhpStorm will create the required tags or add an empty documentation stub.

If you need additional PHP-specific tags, PhpStorm provides code completion that suggests the tag names that are relevant in the current context. If a certain tag has multiple values, code completion provides a list of available values.

In PHPDoc comments, PhpStorm supports formatting options in compliance with the ZEND, PEAR, and other coding standards.

PHPDoc comments in your source code are available for Quick Documentation Lookup, which helps you get quick information for any documented symbol. You can open them for review in the Documentation tool window by pressing Ctrl+Q.

Enable documentation comments

  1. Open the Editor | General | Smart Keys page of PhpStorm settings (Ctrl+Alt+S).

  2. In the Enter section, select or clear Insert documentation comment stub checkbox.

Generate a PHPDoc block for a code construct

  1. To invoke generation of a PHPDoc block, do one of the following:

    • Place the caret before the required code construct (class, method, function, and so on), type the opening block comment /**, and press Enter.

    • In the editor context menu, select Generate | Generate PHPDoc blocks and choose the code construct to generate PHPDoc comments for.

    • Press Alt+Insert, then select Generate PHPDoc blocks, and choose the code construct to generate PHPDoc comments for.

    PhpStorm analyzes the appointed code construct, extracts the data for parameters, return values, variables, or fields where possible, and on this basis generates a stub of a documentation block.

  2. Describe the listed parameters and return values where necessary. PhpStorm checks and treats syntax in comments according to the PHP Inspections settings.

Create tags in a PHPDoc comment block

PhpStorm analyzes the appointed code construct, extracts the data for parameters, return values, variables, or fields where possible, and on this basis generates a stub of a documentation block. If necessary, you can fill in the missing information.

  1. In a PHPDoc block, select the desired empty line and press Ctrl+Space.

  2. Select the relevant tag from the suggestion list.

  3. If the entered tag has several values, press Ctrl+Space and select the desired value from the suggestion list.

Configure formatting inside PHPDoc comments

You can configure the appearance of PHPDoc comments and the presentation of class names. Note that the tag for properties is no longer configurable, the default @var tag is inserted automatically. See https://github.com/phpDocumentor/fig-standards/pull/55 for details.

  1. In the Settings/Preferences dialog (Ctrl+Alt+S), go to Editor | Code Style | PHP.

  2. Switch to the PHPDoc tab an configure the alignment by selecting or clearing the checkboxes.

  3. Specify how you want PhpStorm to present class names for properties, function parameters, return and throws values, and so on, by selecting or clearing the Use fully-qualified class names checkbox.

Using PHPDoc code inspections

PhpStorm provides a set of predefined code inspections targeted at PHPDoc blocks. These inspections check whether classes, methods, functions, variables, and constants are supplied with a PHPDoc comment and whether the tags in the comment match the documented item.

Enable or disable a PHPDoc inspection

  1. In the Settings/Preferences dialog (Ctrl+Alt+S), select Editor | Inspections.

  2. On the Inspections page that opens, expand the PHPDoc node under PHP.

  3. In the list of predefined inspections that opens, enable or disable an inspection by selecting or clearing the checkbox next to it.

Check that PHPDoc comments are provided for code constructs of a certain type

  1. Enable the Missing PHPDoc Comment inspection.

  2. In the Options area, select the checkboxes next to the required element type: class, method, function, variable, or constant.

    To suppress reporting a Missing PHPDoc Comment error if a method or function does not contain any parameters or return values, select the Ignore PHPDoc without @param/@return checkbox.

Last modified: 7 December 2018

See Also