How do I put blocks of PHP code into a PHPDoc DocBlock

Question

I'm playing around with PHPDoc and have realised that you can use markdown to add some formatting to a DocBlock. In particular, I notice that you can use back ticks to highlight inline code.

However, I can't seem to figure out how to add blocks of code to a DocBlock, as using 4 spaces doesn't seem to work.

I've tried using <code> and <pre> too, and whilst those tags do appear in the generated documentation, the code inside them becomes commented out with HTML comments.

For example, this DocBlock:

/**
 * This is a test DocBlock
 *
 * <pre>
 *     <?php
 *         echo('hi');
 *     ?>
 * </pre>
 *
 * @return object[] An array of objects.
 */

Generates this HTML:

<pre>
    <!--?php echo('hi'); ?-->
</pre>

Where am I going wrong? How can I add a block of code to my DocBlock?

Solution 1

phpdocumentor uses the github variant of markdown.

The proper way to add code, is then:

/**
 * This is a test DocBlock
 *
 * ```php
 * echo('hi');
 * ```
 *
 * @return ...
 */

Solution 2

The phpDocumentor manual says that for Descriptions

you can format your text according to Markdown, more specifically Github-flavoured Markdown. Using this format it is easy to make your text bold, add inline code examples or easily generate links to other sites. — Inside DocBlocks

The PSR-5 PHPDoc says for Descriptions

Any application parsing the Description is RECOMMENDED to support the Markdown mark-up language for this field so that it is possible for the author to provide formatting and a clear way of representing code examples. — Description

And that Tags

MUST support Markdown as a formatting language. Due to the nature of Markdown it is legal to start the description of the tag on the same or the subsequent line and interpret it in the same way. — Tag

Example of PHPDoc using Github-Flavoured Markdown

/**
 * This is a Summary.
 *
 * This is a Description. It may span multiple lines
 * or contain 'code' examples using the _Markdown_ markup
 * language.
 *
 * It's very easy to make some words **bold** and other 
 * words *italic* with Markdown. You can even 
 * [link to Google!](http://google.com).
 *
 * Here's an example of how you can use syntax 
 * highlighting with GitHub Flavored Markdown:
 *
 * ```
 * <?php
 * echo "Hello, world.";
 * ?>
 * ```
 * 
 * You can also simply indent your code by four spaces:
 * 
 *     <?php
 *     echo "Hello, world.";
 *     ?>
 *
 * @see Markdown
 *
 * @param int        $parameter1 A parameter description.
 * @param \Exception $e          Another parameter description.
 *
 * @\Doctrine\Orm\Mapper\Entity()
 *
 * @return string
 */
function test($parameter1, $e)
{
    ...
}

Solution 3

I don't think you should be adding the <?php tag, I would assume it will strip it off on parsing. Seeing as phpdoc you can probably skip it alltogether.

try

 * <code>
 *         echo('hi');
 * </code>

Solution 4

You should be able to use:-

/**
 * This is a test DocBlock
 *
 * <pre>
 *     &lt;?php
 *         echo('hi');
 *     ?&gt;
 * </pre>
 *
 * @return object[] An array of objects.
 */

View more solutions