README

由victorjonsson/PHP-Markdown-Documentation-Generator分叉而来

安装

$ composer global require daaquan/php-markdown-documentation-generator

$ php-doc-md -h

旧版本。

PHP-Markdown-Documentation-Generator

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

该项目将基于源代码中的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