如何将 PHP 代码块放入 PHPDoc DocBlock

Posted 2023-02-21

【中文标题】如何将 PHP 代码块放入 PHPDoc DocBlock

【英文标题】：How do I put blocks of PHP code into a PHPDoc DocBlock

【发布时间】：2012-07-29 06:57:28

【问题描述】：

我正在使用 phpDoc，并意识到您可以使用 markdown 向 DocBlock 添加一些格式。特别是，我注意到您可以使用反引号来突出显示内联代码。

但是，我似乎不知道如何将代码块添加到 DocBlock，因为使用 4 个空格似乎不起作用。

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

例如，这个 DocBlock：

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

生成此 HTML：

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

我哪里错了？如何将代码块添加到我的 DocBlock？

【问题讨论】：

你试过用<和>代替<和>吗？

那里的文档说这是正确的用法manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/…

@MikeB 有趣的是，该链接表明它应该可以工作......一直使用< 和> 有点尴尬...... PHPDoc 可以/应该为我转换这些吗？

@MarkLocker Odd - 我也看到了你所看到的。我正在使用 PHPDocumentor 2.0.0a3

在我自己的使用中，我会使用 Kasia，而不使用 PHP 开始/结束标签，因为 块的上下文应该足够清晰。 Mez 让文本等效于标签的方式也应该有效，通过使用文字标签字符避免任何解析器混淆。我还没有尝试过使用双符号（&gt;）来查看它们是否有效，类似于如何使用“&gt;”来打印文字“<b>”（@ 987654322@)</b>

【参考方案1】：

phpdocumentor 使用markdown 的github 变体。

添加代码的正确方法是：

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

【参考方案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)

    ...

【讨论】：

并不是 OP 询问了 Eclipse，但我会注意到 Eclipse-PDT Neon 似乎不支持降价。很遗憾，因为 markdown 比一堆 HTML 标记更易读。

非常好，这个答案引用了文档和几个语法示例。我希望这个答案能获得足够的票数，成为最佳答案。 2016 年 6 月，我一直在寻找这样的确认。

欣赏这些例子。我没有意识到 4 个空格缩进是在空格之后在星号之后。

【参考方案3】：

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

试试

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

【参考方案4】：

你应该可以使用：-

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

【讨论】：

@JunaidAtari Nop，因为它是