40

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?

Improve this question
5
  • Have you tried using &lt; and &gt; instead of < and >? Commented Jul 31, 2012 at 13:36
  • 1
    There documentation says that's the correct usage manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/… Commented Jul 31, 2012 at 13:38
  • 2
    @MikeB Interesting that the link suggests it should work... it's a bit awkward using &lt; and &gt; all of the time... Surely PHPDoc could/should convert these for me? Commented Jul 31, 2012 at 13:42
  • @MarkLocker Odd - I'm also seeing what you're seeing. I'm using PHPDocumentor 2.0.0a3 Commented Jul 31, 2012 at 13:51
  • In my own usage, I would go with Kasia and not use the PHP opening/closing tags, since the context of the <code> blocks should be clear enough. Mez's way of having the text equivalent of the tags should also work, avoiding any parser confusion by using the literal tag characters. Something I have not tried would be using double signs (<<?php and ?>>) to see if they work, analogous to how "<<b>>" can be used to print a literal "<b>" (manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/…) Commented Jul 31, 2012 at 19:48

4 Answers 4

Reset to default
37

phpdocumentor uses the github variant of markdown.

The proper way to add code, is then:

/**
 * This is a test DocBlock
 *
 * ```php
 * echo('hi');
 * ```
 *
 * @return ...
 */
Improve this answer
Sign up to request clarification or add additional context in comments.

Comments

24

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)
{
    ...
}
Improve this answer

5 Comments

Not that the OP asked about Eclipse, but I'll note that Eclipse-PDT Neon doesn't seem to honour markdown. It's a pity, since markdown is more readable inline than a bunch of HTML tags.
Very nice that this answer cites the documentation and several examples of the syntax. I hope this answer gets enough votes to become the top answer. I was looking for a confirmation like this one back in June 2016.
Appreciate the examples. I didn't realize the 4 space indention was after a space following the asterisk.
Markdown does not work in phpstorm. There is a suggestion, but it is years old blog.jetbrains.com/phpstorm/2014/04/…
Update: I discovered markdown is only partitional supported in phpstorm read this for details youtrack.jetbrains.com/issue/WI-15431
12

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>
Improve this answer

Comments

2

You should be able to use:-

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

1 Comment

@JunaidAtari Nop, cause it's <pre>

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.