Question

根据PHPDocumentor的文档，为了显示一个例子，它将是这样的：

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

如果代码永远不会改变，这似乎是一个有效的解决方案，但无论何时去往位置添加新代码，您的起始行都可能发生变化，这意味着您必须不断更新这些不同的引用。

有没有更好的方法来展示如何在DocBlock中使用类方法，而不引用外部当前使用示例？

这是我的目标：

/**
 * @example This is how you use this method:
 *
 *     $baz = Foo::bar( array('bing' => $bing) ); 
 */

然后它在文档中显示为一个例子。有什么想法吗？

Answer 1

您可以通过“代码”分隔符在docblock本身中显示代码示例。所以，对于你原来的例子：

/**
 * This is how you use this method:
 * <code>
 *     $baz = Foo::bar( array('bing' => $bing) ); 
 * </code>
 */

@example标记的手册页[1]既显示docblock中的“code”部分，也显示指向单独文件中的行的@example指针。