如何将PHP代码块放入PHPDoc DocBlock中

Question

我正在玩PHPDoc，并意识到你可以使用markdown为DocBlock添加一些格式。特别是，我注意到您可以使用后退标记来突出显示内联代码。

但是，我似乎无法弄清楚如何向DocBlock添加代码块，因为使用4个空格似乎不起作用。

我也尝试过使用<code>和<pre>，虽然这些标记确实出现在生成的文档中，但其中的代码会被HTML注释注释掉。

例如，这个DocBlock：

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

生成此HTML：

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

我哪里错了？如何向DocBlock添加代码块？

Answer 1

phpdocumentor使用markdown的github变体。

添加代码的正确方法是：

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

Answer 2

phpDocumentor手册说明了描述

  

您可以根据Markdown格式化文字，更具体地说是Github-flavoured Markdown。使用此格式可以轻松地使文本变为粗体，添加内联代码示例或轻松生成指向其他网站的链接。 - Inside DocBlocks

PSR-5 PHPDoc代表描述

  

任何解析说明的应用程序都是推荐用于支持此字段的Markdown标记语言，以便作者可以提供格式化和表示代码示例的清晰方式。 - Description

那标签

  

必须支持Markdown作为格式化语言。由于Markdown的性质，在相同或后续行开始标记的描述并以相同的方式解释它是合法的。 - Tag

使用Github-Flavored Markdown的PHPDoc示例

/**
 * 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)
{
    ...
}

Answer 3

我认为你不应该添加<?php标签，我认为它会在解析时将其剥离。看作是phpdoc你可以完全跳过它。

试

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

Answer 4

您应该可以使用： -

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