PHPDocumentor @example 用法

Question

我似乎无法理解如何获取 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>使某些东西变得糟糕的标签。但这是一个不同的问题。

Answer 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>]}
 */