README

文档与所引用的代码一样重要。使用此命令行工具，您只需编写一次文档即可！

此项目将基于源代码中的DocBlock注释编写单页Markdown格式的API文档。

示例

假设您有一个名为"src"的目录，其中包含PHP类。每个类都有自己的文件，其名称与类名相同。

- src/
  - MyObject.php
  - OtherObject.php

按照 phpdoc 标准编写代码文档。

namespace Acme;

/**
 * This is a description of this class
 */
class MyObject {
   
   /**
    * This is a function description
    * @param string $str
    * @param array $arr
    * @return Acme\OtherObject
    */
   function someFunc($str, $arr=array()) {
   
   }
}

然后，运行 $ phpdoc-md generate src > api.md 将API文档写入api.md文件。

这里是一个渲染示例

只有公共和受保护的函数将是文档的一部分，但您也可以添加 @ignore 到任何函数或类以将其排除在文档之外。Phpdoc-md会尝试猜测未显式声明返回类型的函数的类型。程序使用反射从代码中获取尽可能多的信息，以便即使缺少DocBlock注释的函数也将包含在生成的文档中。

要求

• PHP版本 >= 5.3.2
• 在php.ini中启用Reflection
• 每个类必须定义在其自己的文件中，文件名与类名相同
• 项目应使用 Composer

安装/使用

此命令行工具可以使用 composer 安装。

从您想要文档的项目本地工作目录运行

$ composer require --dev getgrav/markdowndocs

这将把 victorjonsson/markdowndocs 添加到项目 composer.json 文件的 require-dev 部分。phpdoc-md 可执行文件将自动复制到项目的 vendor/bin 目录。

生成文档

generate 命令生成项目的API文档文件。命令行工具需要知道您是否要为某个特定类生成文档，或者是否应该处理指定目录搜索路径中的每个类。

# Generate docs for a certain class
$ ./vendor/bin/phpdoc-md generate Acme\\NS\\MyClass 

# Generate docs for several classes (comma separated)
$ ./vendor/bin/phpdoc-md generate Acme\\NS\\MyClass,Acme\\OtherNS\\OtherClass 

# Generate docs for all classes in a source directory
$ ./vendor/bin/phpdoc-md generate includes/src

# Generate docs for all classes in a source directory and send output to the file api.md
$ ./vendor/bin/phpdoc-md generate includes/src > api.md

• 注意，任何要文档化的类都必须可以使用由composer提供的自动加载器加载。 *

引导

如果您没有使用composer自动加载器，或者在进行类实例化之前需要执行其他操作，则可以要求phpdoc-md在生成文档之前加载php引导文件。

$ ./vendor/bin/phpdoc-md generate --bootstrap=includes/init.php includes/src > api.md

排除目录

您可以使用 --ignore 选项告诉命令行工具忽略类路径中的某些目录。

$ ./phpdoc-md generate --ignore=test,examples includes/src > api.md