README

文档与代码一样重要。使用这个命令行工具，您只需编写一次文档！

本项目将根据源代码中的DocBlock注释生成单页Markdown格式的API文档。

示例

假设您将PHP类放在名为"src"的目录中。每个类都有自己的文件，其文件名与类名相同。

- 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 victorjonsson/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