README

Anodoc

参考源：https://github.com/asartalo/anodoc

主要解决php8以上兼容性问题

======

Anodoc 是用 PHP 编写的轻量级文档注释/块解析器。文档注释通常以以下风格编写

<?php
/**
 * A test summary
 *
 * And here's a longer description that explains in detail
 * what this section is all about.
 *
 * @param  foo bar
 * @param  boo far
 * @return baz
 */
?>

并用于记录源代码。Anodoc 解析这些注释，以便您可以访问描述、简短描述、长描述和标签。

用法

对于前面的示例文档注释，您可以获取如下数据

<?php
$parser = new Anodoc\Parser;

// This returns a new Anodoc\DocComment object.
$doc = $parser->parse(
	"/**\n" .
	" * A test summary\n" .
	" *\n" .
	" * And here's a longer description that explains in detail\n" .
	" * what this section is all about.\n" .
	" *\n" .
	" * @param  foo bar\n" .
	" * @param  boo far\n" .
	" * @return baz\n" .
	" */"
);

echo $doc->getShortDescription();
// "A test summary"

echo $doc->getLongDescription();
// And here's a longer description that explains in detail
// what this section is all about.

echo $doc->getTagValue('return');
// baz

$doc->getTag('return');
// A Tag object with value 'baz'

echo $doc->getTagValue('param'); // this will return the last defined value
// boo far

var_dump($doc->getTags('param'));
// a dump of a TagGroup that has 2 values

?>

您也可以通过 Anodoc 获取一个类上的所有 docComments

<?php

// Factory instantiates a new Anodoc object
// With a Parser
$anodoc = Anodoc::getNew();

$classDoc = $anodoc->getDoc('FooClass');

// Get the main class doc comment description
echo $classDoc->getMainDoc();

// Get the doc comment for method FooClass::fooMethod()
$classDoc->getMethodDoc('fooMethod')

// Get the doc comment for the attribute $bar
$classDoc->getAttributeDoc('bar');
?>

自定义标签

Anodoc 没有定义任何针对标签值的语法定制。默认情况下，从解析器检索的每个值都返回 Anodoc\Tags\GenericTag 实例。您可以通过创建一个扩展抽象类 'Anodoc\Tags\Tag' 的类并通过对解析器或 Anodoc 对象进行注册来注册一个新的标签类型。然后您可以在那里设置您的自定义语法。

例如，Anodoc 内置了一个名为 "Anodoc\Tags\ParamTag" 的自定义标签来处理参数。定义如下

<?php

namespace Anodoc\Tags;

class ParamTag extends Tag {

  private $tag_name, $value;

  function __construct($tag_name, $value) {
    preg_match('/(\w+)\s+\$(\w+)\s+(.+)/ms', $value, $matches);
    $this->value = array(
      'type' => $matches[1],
      'name' => $matches[2],
      'description' => $matches[3]
    );
    $this->tag_name = $tag_name;
  }

  function getValue() {
    return $this->value;
  }

  function getTagName() {
    return $this->tag_name;
  }

  function __toString() {
    return (string) $this->value;
  }

}
?>

这默认未注册，因此您必须自己注册以使其有用。

<?php

$anodoc = Anodoc::getNew();
$anodoc->registerTag('param', 'Anodoc\Tags\ParamTag');
$classDoc = $anodoc->getDoc('FooClass');

$param = $classDoc->getMethodDoc('fooMethod')->getTag('param');
// returns an 'Anodoc\Tags\ParamTag' object

$param->getValue();
// if the param tag looks like this:
//     @param string $firstName the first name of the person
// The value would be:
// array(
//     'type' => 'string', 'name' => 'firstName',
//     'description' => 'the first name of the person'
// )

?>

限制

Anodoc 目前不解析内联标签。