PHPDocumentor @example 用法答案

【问题标题】：PHPDocumentor @example usagePHPDocumentor @example 用法
【发布时间】：2014-04-16 21:33:29
【问题描述】：

我似乎无法理解如何让 PHPCocumentor2 @example 标签正常工作。

我正在尝试解析单个文件。我的工作目录是/home/developers/domains/example.com，我正在尝试解析（相对于我的工作目录）simplesamlphp/modules/example/lib/Auth/Process/RoleTrigger.php。这个类文件有一个 DocBloc，看起来像：

/**
 * Trigger Role on User from Configuration.
 *
 * @example "RoleManager.usage.example.php" Test Example
 */
public function process() { /* ... */ }

当我运行命令以最大详细度（phpdoc -f simplesamlphp/modules/example/lib/Auth/Process/RoleTrigger.php -t httpdocs/test -vvv）解析此文件时，PhpDoc 指示当前项目根目录为/home/developers/domains/example.com/simplesamlphp/modules/example/lib/Auth/Process/，因此，根据文档，这表明示例文件RoleManager.usage.example.php 应该位于已解析文件的同一目录级别，或位于当前项目根目录的examples 目录中（即/home/developers/domains/example.com/simplesamlphp/modules/example/lib/Auth/Process/examples/）。

但是，尽我所能，我似乎无法让示例显示在生成的文档中。

我似乎得到的是，在生成页面的右侧：

Tags
example     Test Example

没有超链接，或显示文件内容，或任何东西。只是“描述”，没有其他内容。

我曾尝试使用<code>，但多行具有多个级别会渲染损坏的 html，这也是无用的：

这个：

/**
 * Test Doc
 *
 * <code>
 * <?php
 * $array = array(
 *     1 => 'one',
 *     2 => 'two',
 * );
 * print_r($array);
 * ?>
 * </code>
 */

呈现以下 HTML：

<p><code>
&lt;?php
$array = array(</p>
<pre><code>1 =&gt; 'one',
2 =&gt; 'two',</code></pre>
<p>);
print_r($array);
?>
</code></p>

多个嵌套的 <code> 和 <pre> 标签会渲染一些糟糕的东西。但这是一个不同的问题。

【问题讨论】：

标签： php phpdoc phpdocumentor2

【解决方案1】：

当我最初发布此问题时，@example 标签在 PHPDocumentor v2 中尚未实现（尚未）。对于许多标签来说这是一个不幸的事实，因为 PHPDocumentor v2 是建立在与 v1 完全不同的基础之上的，并且标签已经/仍在被移植到新系统。

在我发布问题后不久，我与从事该项目的 Git 社区联系，并为实现 @example 标签的任务做出了一些贡献。

此时，标签按预期工作并在 PHPDoc 文档中定义，到 T（据我测试）。

http://www.phpdoc.org/docs/latest/references/phpdoc/tags/example.html

我确实想到，由于现在按预期工作，因此可能不再需要此问题（和答案）。但是我想确保我更新了它，以免有人偶然发现它并感到困惑。

为了完整起见，在撰写本文时，语法执行如下：

/**
 * @example [location] [<start-line> [<number-of-lines>] ] [<description>]
 */

/**
 * Or inline {@example [location] [<start-line> [<number-of-lines>] ] [<description>]}
 */

【讨论】：