Creating PHP Documentation Comments
On this page:
- Enabling generation of documentation comments
- Generating a PHPDoc block for a method or a function
- Creating tags in a PHPDoc comment block
- Inspecting PHPDoc comments
- Configuring formatting inside PHPDoc comments
PhpStorm creates stubs of PHPDoc blocks
on typing the opening tag
/** and pressing Enter or pressing Alt+Insert and appointing the method.function to document.
If this feature is applied to a method or a function,
@abstract tags are created.
In any other places PhpStorm adds an empty documentation stub.
If you need additional PHP-specific tags, PhpStorm provides code completion that suggests tag names that are relevant in the current context. If a certain tag has multiple values, the same code completion provides a list of available values.
In PHPDoc comments, PhpStorm supports formatting options in compliance with ZEND, PEAR, and other standards.
PHPDoc comments in your source code are available for the Quick Documentation Lookup feature and open for review on pressing Ctrl+Q.
To enable or disable generation of documentation comments
Generating a PHPDoc block for a method or a function
To invoke PHPDoc block generation, do one of the following:
Place the caret before the method or function declaration, type the opening block comment
/**, and press Enter.
- On the context menu anywhere in the editor, choose Generate, then choose Generate PHPDoc blocks, and choose the method or function to generate comments for.
- Press Alt+Insert, then choose Generate PHPDoc blocks, and choose the method or function to generate comments for.
PhpStorm analyzes the appointed method or function, where possible extracts the data for method parameters, return values, variables, etc., and on this basis generates a stub of a documentation block.
- Place the caret before the method or function declaration, type the opening block comment
- Describe the listed parameters and return values, where necessary.
Creating tags in a PHPDoc comment block
- In a PHPDoc block, select the desired empty line and press Ctrl+Space.
- Select the relevant tag from the suggestion list.
- If the entered tag has several values, press Ctrl+Space and select the desired value from the suggestion list.
Inspecting PHPDoc comments
To enable or disable an inspection:
- Choose File | Settings on the main menu, and in the Settings dialog box that opens, click Inspections.
- On the Inspections page that opens, expand the PHPDoc node under the PHP node. The list of predefined inspections is displayed.
- To enable or disable an inspection, select or clear the check box next to it.
To have PhpStorm check that PHPDoc comments are provided for all code constructs of a certain type:
- Select the check box next to the Missing PHPDoc Comment inspection.
- In the Options area, select the check boxes next to the required code construct 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 and/or return values, select the Skip if empty.
Configuring formatting inside PHPDoc comments
- Open the Settings dialog box, click Code Style, then click PHP, and switch to the PHPDoc tab.
- Configure the alignment by selecting or clearing the check boxes in the tab.
- Specify how you want PhpStorm to present class names for properties, function parameters, return and throws values, etc. by selecting or clearing the Use fully-qualified class names check box.
From the Tag type drop-down box, choose the tag to use for properties, the available options are
@type. According to the PSR5 standards, @var is deprecated and it is recommended that you use @type for properties instead.