ディスカッション: PhpDocumentor を使用してドキュメントを生成する方法_PHP チュートリアル

命令行方式：
　　在phpDocumentor所在目录下，输入phpdoc –h会得到一个详细的参数表，其中几个重要的参数如下：
-f 要进行分析的文件名，多个文件用逗号隔开
-d 要分析的目录，多个目录用逗号分割
-t 生成的文档的存放路径
-o 输出的文档格式，结构为输出格式：转换器名：模板目录。
　 例如：phpdoc -o HTML:frames:earthli -f test.php -t docs

Web界面生成
　　在新的phpdoc中，除了在命令行下生成文档外，还可以在客户端浏览器上操作生成文档，具体方法是先把PhpDocumentor的内容放在apache目录下使得通过浏览器可以访问到，访问后显示如下的界面：
　　点击files按钮，选择要处理的php文件或文件夹，还可以通过该指定该界面下的Files to ignore来忽略对某些文件的处理。
　　然后点击output按钮来选择生成文档的存放路径和格式.
　　最后点击create，phpdocumentor就会自动开始生成文档了，最下方会显示生成的进度及状态，如果成功，会显示
Total Documentation Time: 1 seconds
done
Operation Completed!!
然后，我们就可以通过查看生成的文档了，如果是pdf格式的，名字默认为documentation.pdf。
给php代码添加规范的注释

PHPDocument是从你的源代码的注释中生成文档，因此在给你的程序做注释的过程，也就是你编制文档的过程。
　　从这一点上讲，PHPdoc促使你要养成良好的编程习惯，尽量使用规范，清晰文字为你的程序做注释，同时多多少少也避免了事后编制文档和文档的更新不同步的一些问题。
　　在phpdocumentor中，注释分为文档性注释和非文档性注释。
　　所谓文档性注释，是那些放在特定关键字前面的多行注释，特定关键字是指能够被phpdoc分析的关键字，例如class，var等，具体的可参加附录1.
　　那些没有在关键字前面或者不规范的注释就称作非文档性注释，这些注释将不会被phpdoc所分析，也不会出现在你产生的api文当中。

ドキュメント コメントの書き方:
すべてのドキュメント コメントは、/**最初の複数行のコメントは、phpDocumentor では DocBlock と呼ばれます。DocBlock は、他の人がこのキーワードの具体的な目的とその使用方法を知ることができるように、ソフトウェア開発者によって作成された特定のキーワードに関するヘルプ情報を指します。 PhpDocumentor では、DocBlock に次の情報が含まれると規定しています:
1. 関数の簡単な説明領域
2. 詳細な説明領域
3. ドキュメントのコメントの最初の行は関数の説明領域であり、テキストは通常​​、クラスの簡潔さ、メソッドまたは関数の機能、および関数の簡単な説明のテキストが、生成されたドキュメントのインデックス領域に表示されます。関数説明領域の内容は、空白行で終了することもできます。
関数説明領域の後には、詳細な説明領域が続きます。この部分は、主に API の機能と目的を詳細に説明します。可能であれば、使用例なども教えてください。このセクションでは、API 関数またはメソッドの一般的な目的と使用法を明確にすることに重点を置き、それがクロスプラットフォームであるかどうか (関係する場合) を示す必要があります。プラットフォーム関連の情報については、一般的な情報とは異なるものとして扱う必要があります。通常のアプローチは、新しい行を開始してから、特定のプラットフォームに関する注意事項や特別な情報を書き込むことです。この情報は、読者が境界条件、パラメーター範囲、ブレークポイントなどの対応するテスト情報を書き込むことができるようにするのに十分です。

その後も空行があり、ドキュメントタグがあり、主に呼び出しパラメータの型、戻り値と型、継承関係、関連するメソッド/関数などの技術情報を示します。

ドキュメントのコメントでは などのタグを使用することもできます。詳しくは、付録 2 を参照してください。

ドキュメントコメントの例
/**
* 関数 add、2 つの数値の加算を実装します*
* 単純な加算計算、関数は 2 つの数値 a と b を受け入れ、それらの合計 c を返します
*
* @param int addend
* @param int addend
* @return integer
*/
function Add($a, $b)
{
return $a+$b;
}
によって次のように生成されます。 Add
integer Add(int $a, int $b)
[line 45]
関数 add は 2 つの数値の加算を実装します
定数 単純な加算計算、関数は 2 つの数値 a と b を受け取り、それらを返します c の合計
パラメータ
• int $a - addend
• int $b - summand

Document タグ:

document タグの使用範囲は、そのタグを使用して変更できるキーワード、または他の document タグを指します。 すべてのドキュメントタグは、各行の * の後に @ で始まります。 @マークが段落の途中にある場合、通常の内容として扱われ無視されます。
@access

使用範囲：class、function、var、define、module このタグは、キーワードのアクセス許可を示すために使用されます：private、public、protected
@author

作者を指定します
@copyright
使用範囲:class、function、var、define、module、use著作権情報を指定
@deprecated

使用範囲:class、function、var、define、module、constent、global、include未使用またはを指定廃止されたキーワード
@example

このタグは、ファイルの内容を解析して強調表示するために使用されます。 Phpdoc は、このタグで指定されたファイル パスからファイルの内容を読み取ろうとします
@const
使用範囲:define PHP で定義された定数を指定するために使用されます
@final

使用範囲:class、function、var指定 キーワードは最終的なクラス、メソッド、または属性であり、派生または変更することは禁止されています。
@filesource

例と似ていますが、このタグが現在解析されているphpファイルの内容を直接読み取って表示する点が異なります。
@global
この関数で参照されるグローバル変数を示します
@ingore
ドキュメント内の指定されたキーワードを無視するために使用されます
@license
HTMLタグのに相当し、最初はURLです、その後に表示するコンテンツが続きます 例: Baidu
@license http://www.baidu.com Baidu と書くことができます
@link

license に似ています ただし、リンクを通じてドキュメント内の任意のキーワードをポイントすることもできます
@name

キーワードのエイリアスを指定します。
@package
使用範囲: ページレベル ->define、function、include; クラスレベル ->class、var、methods
1 つまたは複数のキーワードを論理的にグループ化するために使用されます。
@abstrcut

現在のクラスが抽象クラスであることを示します
@param
関数のパラメータを指定します
@return
メソッドまたは関数の戻りポインタを示します
@static
キーワードは静的です。
@var
変数の型を指定
@version
バージョン情報を指定
@todo
改善すべき箇所や実装しない箇所を指定
@throws
この関数が発生する可能性のあるエラー例外を指定極端な場合にはスローします
上で述べたように、通常のドキュメント タグは各行の先頭に @ を付ける必要があります。さらに、{@} で表されるインライン タグと呼ばれるタグもあり、これには具体的には次のものが含まれます。 { @link}
使い方は @link と同じ
{@source}
関数またはメソッドの内容を表示します