README

别名：Peej的快速PHPDoc克隆

PHPDoctor是一个PHP风格的注释解析器，注重速度和简洁。它旨在尽可能接近Javadoc。

安装

您可以从Github克隆它，但最好使用Composer在您的项目中安装

{
    require: "peej/phpdoctor": "2.0.5"
}

然后运行Composer

$ curl -s https://getcomposer.org/installer | php
$ composer.phar install

然后如果一切按计划进行，使用默认配置运行PHPDoctor

$ bin/phpdoc

配置

PHPDoctor将以默认选项运行，处理当前目录及其以下所有*.php文件，除非您提供了配置文件。

配置通过PHP风格的ini文件完成。如果当前目录中有一个名为phpdoctor.ini的文件，PHPDoctor将使用此文件，或者您可以将配置文件名作为第一个命令行选项传入。

PHPDoctor支持许多配置指令

• files - 要解析的文件名。这可以是一个单个文件名，也可以是逗号分隔的文件名列表。允许通配符。
• ignore - 要忽略的文件名或目录名。这可以是一个单个文件名，也可以是逗号分隔的文件名列表。不允许通配符。
• source_path - 要查找文件的目录，如果不使用，PHPDoctor将在当前目录（运行目录）中查找。
• subdirs - 如果您不希望PHPDoctor在每个子目录中查找文件，取消此行注释。
• quiet - 静默模式会抑制所有输出，除了警告和错误。
• verbose - 详细模式会在执行过程中输出额外的消息。
• doclet - 选择用于生成输出的doclet。
• doclet_path - 查找doclet的目录。Doclets应位于给定位置以自身命名的目录中。
• taglet_path - 查找taglets的目录。Taglets允许您让PHPDoctor处理新标签，并更改现有标签及其输出的行为。
• default_package - 如果您正在解析的代码不使用包标签或不是所有元素都有包标签，请使用此设置将未绑定元素放入特定包。
• overview - 指定包含概述文档文本的HTML文件名，该文档将放置在概述页上。路径相对于"source_path"，除非指定了绝对路径。
• package_comment_dir - 在该包中解析的第一个源文件所在的同一目录中的名为package.html的文件中查找包注释。或者，如果使用以下指令，则包注释应命名为".html"。
• globals - 解析全局变量。
• constants - 解析全局常量。
• private - 为所有类成员生成文档。
• protected - 为公共和受保护的类成员生成文档。
• public - 仅生成公共类成员的文档。

以下指令是针对标准doclet的特定指令

• d - 放置生成的文档的目录。如果给定的路径是相对的，它将相对于"source_path"。
• 窗口标题 - 指定要在 HTML <title> 标签中放置的标题。
• 文档标题 - 指定要放置在概述摘要文件顶部的标题。
• 页眉 - 指定要放置在每个输出文件顶部的页眉文本。页眉将放置在上部导航栏的右侧。
• 页脚 - 指定要放置在每个输出文件底部的页脚文本。页脚将放置在下部导航栏的右侧。
• 底部 - 指定要放置在每个输出文件底部的文本。文本将放置在页面底部，位于下部导航栏下方。
• 树 - 创建一个类树

文档注释

关于文档注释格式的完整描述可以在 Sun Javadoc 网站上找到（http://java.sun.com/j2se/javadoc/）。文档注释看起来像这样

/**
 * This is the typical format of a simple documentation comment
 * that spans two lines.
 */

标签

PHPDoctor 支持以下标签在文档注释中

@author name-text
@deprecated deprecated-text
{@link package.class#member label}
{@linkplain package.class#member label}
@param parameter-type parameter-name description
@return return-type description
@see packahge.class#member
@since since-text
@var var-type
@version version-text

一些 Javadoc 标签与 PHP 不相关，其他标签由于 PHP 的松散类型而添加或略有改变。

问题

Q：为什么我们需要另一个 PHPDdoc 克隆？

A：我编写 PHPDoctor 是因为我在 2004 年，找不到一个小巧、简单且开箱即用或真正工作的 PHP Javadoc 克隆。PHP 标记扩展使得创建 PHPDoc 程序变得非常容易，因为现在 PHP 可以为你完成繁重的工作。

Q：PHPDoctor 与其他 PHPDoc 程序有什么不同？

A：PHPDoctor 非常小巧且易于使用，尽可能模仿 Javadoc 的工作方式，包括使用相同的程序结构和模板化 doclet 方法。PHPDoctor 的学习曲线非常小，大多数人应该只需要几分钟就能生成 API 文档。

Q：请告诉我更多关于 PHPDoctor 的工作方式

A：PHPDoctor 使用 PHP 标记扩展，这意味着它让 PHP 解析你的源代码。PHPDoctor 只是从 PHP 解析出的标记中提取，并通过 doclet 类将它们转换为 API 文档。这意味着它适用于任何有效的 PHP 代码，没有例外，这也使它非常快。