README

Annotiny

Annotiny 是一个用于读取和解析文档注释的轻量级库。

用法

要创建 AnnotationReader 对象，需要提供一个合适的解析器。

$parser = new \Annotiny\AnnotationParser(new \Annotiny\AnnotationContainer);
$annotationReader = new \Annotiny\AnnotationReader($parser, $factory);

注释提供了四个公共方法：readClass($class)、readFunction($function)、readMethod($class, $method) 和 readProperty($class, $property)。这些函数按预期工作，例如 readMethod 会读取并解析类或对象的文档注释。

注释对象

一个 read* 方法的结果是一个 Comment 实例。注释包含文档注释的描述和解析后的标签。

注释提供了一些有用的方法来处理注释标签。

• has($tag) 检查是否存在标签
• get($tag) 获取标签值
• equals($tag, $value) 检查 $tag 的值是否等于 $value
• contains($tag, $value) 检查 $value 是否在注释的参数列表中
• containsAll($tag, $value_array) 检查 $value_array 中的每个成员是否都存在
• getDescription() 返回注释的描述部分

如果找不到标签，将抛出 OutOfBoundsException。

注释语法

文档注释直接位于被注释的类、函数、方法或属性上方（例如，之间没有空行）。注释以 /** 开头，以 */ 结尾。每一行可以可选地以星号 (*) 开始。

注释以描述部分开始，以 @tag 结束。

示例

/** This is a one-liner */

/**
 * Multiple lines
 *
 * @annotation
 */

注释语法

注释标签以反引号 (@) 开头，并且它们从新的一行开始。标签名称可以由字母、数字、破折号 (-) 和下划线 (_) 组成，但必须以至少一个字母开头。以下是不合法的标签名称示例：@1tag、@-tag。

有三种类型的注释

• 没有值的简单注释 (@tag)
• 后跟其值的注释 (@tag that has a value)。
• 后跟参数列表的注释 (@tag(value, 'other value'))。

值由逗号分隔的字符串组成。在第二种情况下只允许一个值，逗号及其后面的文本将被丢弃。第三种情况允许多个值，这些值由逗号分隔。要允许值中的逗号和新行，只需将其括在单引号或双引号中。

如果存在多个具有相同名称的注释，它们的值将汇总到一个数组中。在这种情况下，没有值的注释将被忽略。

注意：支持参数列表语法的命名参数。在这种情况下，一个 = 符号将名称和值分开。

示例

• @tag
• @tag value
• @tag "some value"
• @tag()
• @tag(simple value)
• @tag(multiple, values)
• @tag(name='value')