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.
 */