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: <pre>*
* // This is a code fragment
* $this->x = 0;
</pre> </li> </ul> <em>Note</em>: It is possible to use HTML markup in combination with Markdown. And finally, a larger sample: <pre><code> /** * # MyClass Documentation * * Describes _how to use_ the class with some examples: *
* // Create new instance
* $obj = new MyClass();
* HTML tags are properly escaped: *
* * 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