PhpStorm 8: Markdown Support in PHPDoc Blocks
Since PhpDocumentor allows Markdown in documentation blocks (as stated here), we have added Markdown support to PhpStorm 8 too when showing a quick documentation of classes, functions, etc. Here is a list of what is actually supported from Markdown syntax specification, with some examples:
- Paragraphs separated by one or more line breaks. There is a continuous flow of text inside a paragraph without line breaks from the original description.
- Headers. You can use the following style, for example:
My Header OR My Header --------- =========
or use the number sign (#):
# My Header 1 ## My Header 2
- Emphasis. A piece of text surrounded with underscore characters (_) or asterisks (*) is rendered as underlined. You can also use double asterisks (**) to make it bold. Note that if the underscore character appears inside a name, for example my_variable, it is left as is.
- Lists. You can use asterisks (*) or short dashes (-) at the beginning of a line to mark a list item. For example:
... * * First item * * Second item * * Third item
These will be translated to an HTML list as follows:
- First item
- Second item
- Third item
- Code blocks. Wrap the code into backtick quotes (`) as follows:
* ``` * // This is a code fragment * $this->x = 0; * ```
Note: It is possible to use HTML markup in combination with Markdown.
And finally, a larger sample:
/** * # MyClass Documentation * * Describes _how to use_ the class with some examples: * ``` * // Create new instance * $obj = new MyClass(); * ``` * HTML tags are properly escaped: * ``` * <html><div></div></html> * ``` * Steps: * * Step 1 * * Step 2 * * Step 3 * * **Note:** <i>Some important note.</i> */
The example above will be rendered like so:
If you find anything that can be improved or is not working as expected, please share your feedback in the issue tracker. Thanks!
Develop with pleasure!
-JetBrains PhpStorm Team