README

块注释文档的解析器。

安装和文档

• 作为 Composer 包 eloquent/blox 提供。
• API 文档 可查。

什么是 Blox？

Blox 是一个 PHP 块注释文档的解析器。 Blox 允许将标准的文档块注释解析成对象树表示形式，并提供简单的接口来检索信息。

使用

use Eloquent\Blox\BloxParser;

$blockComment = <<<'EOD'
/**
 * This is the summary.
 *     This is also the summary.
 *
 * This is the body.
 *
 * This is also the body.
 *
 * @tagA This is some tag content.
 * @tagA This is some more tag content.
 * @tagB This is content for a different tag
 *     which spans multiple lines.
 *
 * This is ignored.
 */
EOD;

$parser = new BloxParser;
$block = $parser->parseBlockComment($blockComment);

echo $block->summary(); // outputs 'This is the summary. This is also the summary.'
echo $block->body();    // outputs "This is the body.\n\nThis is also the body."

// outputs 'This is some tag content.', then 'This is some more tag content.'
foreach ($block->tagsByName('tagA') as $tag) {
    echo $tag->content();
}

$splatTags = $block->tagsByName('tagB');
echo array_pop($splatTags)->content(); // outputs 'This is content for a different tag which spans multiple lines.'

约定

Blox 对于块注释有一小套约定。它们的目的是相当宽松的，这样 Blox 就可以使用，无论使用的正文文本格式如何。

摘要文本

摘要文本从第一行非空白文本开始，直到遇到空白行或块结束。行首的空白和换行符被合并为一个空格。

/**
 * This is the summary.
 *     This is also the summary.
 *
 * This is not the summary.
 */

正文文本

正文文本从摘要之后的第一个非空白行开始，直到遇到标签或块结束。空白和换行符保持不变。

/**
 * This is not the body.
 *
 * This is the body.
 *
 * This is also the body.
 *
 * @tagA This is not the body.
 */

标签

标签是任何以 'at' 符号 (@) 开头，后跟一个或多个 'word' 字符（如 PCRE 中定义）的行。这些 'word' 字符构成了标签的 'name'。

标签可以可选地跟随着与标签相关联的内容。标签名称后面的空白被忽略，但随后的文本包含在标签内容中，以及随后的行，直到遇到空白行或另一个标签。行首的空白和换行符被合并为一个空格。

/**
 * This is not a tag.
 *
 * @tagA This is some tag content.
 * @tagA This is some more tag content.
 * @tagB This is content for a different tag
 *     which spans multiple lines.
 *
 * This is ignored.
 */