PHPDocumentor は、PHP で書かれたツールで、標準のアノテーションを備えた PHP プログラムに対して、相互参照、インデックス作成、その他の機能を備えた API ドキュメントを迅速に生成できます。古いバージョンはphpdocです。
1.phpDocumentorとは何ですか?
PHPDocumentor は、PHP で書かれたツールで、標準のアノテーションを備えた PHP プログラムに対して、相互参照、インデックス作成、その他の機能を備えた API ドキュメントを迅速に生成できます。旧バージョンは phpdoc でしたが、1.3.0 からは phpDocumentor に名前が変更されました。同時に、クライアントのブラウザ上でドキュメントを生成し、ドキュメントを phpDocumentor に変換できるようになりました。 PDF、HTML、CHM にはいくつかの形式があり、非常に便利です。
PHPDocumentor が動作すると、指定されたディレクトリの下にある PHP ソース コードをスキャンし、キーワードをスキャンし、分析が必要なコメントをインターセプトし、コメント内の特別なタグを分析し、XML ファイルを生成し、次の情報に基づいて分析されたクラスとモジュール、対応するインデックスの確立、xml ファイルの生成、およびカスタマイズされたテンプレートを使用して、生成された xml ファイルの指定された形式でファイルを出力します。
2.phpDocumentorをインストールする
pear の他のモジュールと同様、phpDocumentor のインストールも自動インストールと手動インストールの 2 つの方法に分かれています。どちらの方法も非常に便利です。
ａ． pear を介して自動的にインストールし、コマンドラインに入力します
pear インストール PhpDocumentor
b. http://manual.phpdoc.org/で PhpDocumentor の最新バージョン (現在 1.4.0) を手動でインストールし、コンテンツを解凍します。
3． PhpDocumentor を使用してドキュメントのコマンド ラインを生成する方法:
phpDocumentor が配置されているディレクトリに次のように入力します。
php-h
詳細なパラメータ リストが表示されます。そのうちのいくつかの重要なパラメータは次のとおりです。
-f 分析するファイルの名前。カンマで区切られた複数のファイル
-d 分析対象のディレクトリ。カンマで区切られた複数のディレクトリ
-t 生成されたドキュメントの保存パス
-o 出力ドキュメント形式。構造は、出力形式: コンバータ名: テンプレート ディレクトリです。
例: phpdoc -o HTML:frames:earthli -f test.php -t docs
Web インターフェイスは新しい phpdoc で生成されます。コマンド ラインでドキュメントを生成することに加えて、具体的な方法としては、最初に PhpDocumentor のコンテンツを Apache ディレクトリに配置することもできます。ブラウザ経由でアクセスすると、アクセス後に次のインターフェイスが表示されます。
ファイル ボタンをクリックして、処理する PHP ファイルまたはフォルダーを選択します。このインターフェイスで無視するファイルを指定することにより、特定のファイルの処理を無視することもできます。
次に、出力ボタンをクリックして、生成されるドキュメントの保存パスと形式を選択します。
最後に「作成」をクリックすると、phpdocumentor が自動的にドキュメントの生成を開始し、成功した場合は生成の進捗状況が下部に表示されます。
ドキュメントの合計時間: 1 秒
終わり
作戦完了!!
次に、生成されたドキュメントが PDF 形式の場合、名前はデフォルトで document.pdf になります。
4. PHPコードに標準コメントを追加する
PHPDocument はソース コード内のコメントからドキュメントを生成するため、プログラムにコメントするプロセスはドキュメントをコンパイルするプロセスでもあります。
この観点から、PHPdoc は、適切なプログラミング習慣を身につけ、仕様書とクリア テキストを使用してプログラムに注釈を付けるよう努めることを奨励します。同時に、ドキュメントの準備とドキュメントの間の非同期の問題を多かれ少なかれ回避します。その後のアップデート。
phpdocumentor では、コメントはドキュメント コメントとドキュメント以外のコメントに分類されます。
いわゆるドキュメントコメントは、特定のキーワードの前に配置される複数行のコメントです。特定のキーワードとは、class、var など、phpdoc で分析できるキーワードを指します。詳細については、付録 1 を参照してください。
キーワードの前にないコメント、または標準化されていないコメントは非ドキュメント コメントと呼ばれ、これらのコメントは phpdoc によって分析されず、生成する API テキストには表示されません。
3.2 ドキュメントコメントの書き方:
すべてのドキュメント コメントは /** で始まる複数行のコメントであり、phpDocumentor では DocBlock と呼ばれます。DocBlock は、ソフトウェア開発者がキーワードの特定の目的を知ることができるように作成された、特定のキーワードに関するヘルプ情報を指します。そしてそれらの使い方。 PhpDocumentor は、DocBlock に次の情報が含まれることを指定します。
1. 機能概要説明エリア
2. 詳細説明エリア
3.タグ付け
ドキュメント コメントの最初の行は関数の説明領域で、通常、このクラス、メソッド、または関数の機能を簡単に説明します。関数の説明のテキストは、生成されたドキュメントのインデックス領域に表示されます。関数説明領域の内容は空行で終了することもできます。関数説明領域の後には、可能であれば、主に API の機能と目的を詳しく説明します。使用例などもご覧いただけます。このセクションでは、API 関数またはメソッドの一般的な目的と使用法を明確にすることに重点を置き、それがクロスプラットフォームであるかどうか (関係する場合) を示す必要があります。プラットフォーム関連の情報については、一般的な情報とは異なるものとして扱う必要があります。通常のアプローチは、新しい行を開始してから、特定のプラットフォームに関する注意事項や特別な情報を書き込むことです。この情報は、読者が境界条件、パラメーター範囲、ブレークポイントなどの対応するテスト情報を書き込むことができるようにするのに十分です。
その後に空白行があり、ドキュメントタグがあり、主に呼び出しパラメータの型、戻り値と型、継承関係、関連するメソッド/関数などの技術情報を示します。
文書のマーキングについては、セクション 4: 文書のマーキングを参照してください。
<b> <code> などのタグはドキュメントのコメントでも使用できます。詳細については、付録 2 を参照してください。
以下はドキュメント コメントの例です
/**
* 関数 add、2 つの数値の加算を実装します
*
* 単純な加算計算。この関数は 2 つの数値 a と b を受け取り、それらの合計 c を返します。
*
* @param int 加数
* @param int サマンド
* @return 整数
*/
関数 Add($a, $b) {
$a+$b を返します。
ドキュメント
は次のとおりです。
追加
整数 Add(int $a, int $b)
[45行目]
関数 add、2 つの数値の加算を実装します
定数は単純な加算計算です。この関数は 2 つの数値 a と b を受け取り、それらの合計 c を返します。
パラメータ
• int $a - 加数
• int $b - 加数
5.ドキュメントタグ:
ドキュメント タグの使用範囲とは、タグを使用して変更できるキーワードまたはその他のドキュメント タグを指します。
すべてのドキュメント タグは、各行の * の後の @ で始まります。 @マークが段落の途中にある場合、通常の内容として扱われ無視されます。
@アクセス
使用範囲: クラス、関数、変数、定義、モジュール
このタグは、キーワードのアクセス権 (プライベート、パブリック、保護) を示すために使用されます。
@著者
著者を指定する
@著作権
使用範囲: クラス、関数、変数、定義、モジュール、使用
著作権情報を指定する
@非推奨
使用範囲: クラス、関数、変数、定義、モジュール、コンテンツ、グローバル、インクルード
未使用または廃止されたキーワードを示します
@例
このタグは、ファイルのコンテンツの一部を解析し、それを強調表示するために使用されます。 Phpdoc は、このタグで指定されたファイル パスからファイルの内容を読み取ろうとします。
@const
使用範囲: 定義
PHPで定義された定数を示すために使用されます。
@ファイナル
使用範囲: クラス、関数、変数
キーワードが最終的なクラス、メソッド、または属性であり、派生または変更が禁止されていることを示します。
@ファイルソース
例と似ていますが、このタグは現在解析されている php ファイルの内容を直接読み取って表示する点が異なります。
@グローバル
この関数で参照されるグローバル変数を示します
@インゴア
ドキュメント内の指定されたキーワードを無視するために使用されます
@ライセンス
HTML タグの <a> に相当します。最初に URL があり、次に表示されるコンテンツが続きます (<a href=”http://www.baidu.com”>Baidu</a> など)。
@license http://www.baidu.com Baidu と書くことができます。
@リンク
免許証に似たもの
ただし、リンクを通じてドキュメント内のキーワードを指定することもできます。
@名前
キーワードのエイリアスを指定します。
@パッケージ
使用範囲: ページレベル -> 定義、関数、インクルード
クラスレベル -> クラス、変数、メソッド
1 つまたは複数のキーワードを論理的に 1 つのグループにグループ化するために使用されます。
@abstrcut
現在のクラスが抽象クラスであることを示します
@param
関数のパラメータを指定する
@戻る
メソッドまたは関数の戻りポインタを指定します
@静的
キーワードが静的であることを示します。
@var
変数の型を指定する
@バージョン
バージョン情報を指定する
@todo
改善すべき領域、または実装しない領域を示します
@throws
極端な場合、上記のように、通常のドキュメント タグは各行の先頭に @ を付ける必要があります。また、{@ } を使用するインライン タグと呼ばれるタグもあります。 、具体的には次のものが含まれます。
{@リンク}
使い方は@linkと同じです
{@ソース}
関数またはメソッドの内容を表示する
6．一部のアノテーション仕様
a. コメントは次のようにする必要があります。
/**
* XXXXXXX
*/
形状
b. グローバル変数を参照する関数の場合は、glboal タグを使用する必要があります。
c. 変数の場合、その型は var (int、string、bool...) でマークされる必要があります。
d. 関数は、param タグと return タグを通じてそのパラメータと戻り値を指定する必要があります。
e. 2 回以上出現するキーワードについては、ingore によって冗長なキーワードを無視し、1 つだけを残します。
f. 他の関数やクラスが呼び出される場合は、ドキュメントを読みやすくするために、リンクまたは他のタグを使用して対応する部分にリンクする必要があります。
g. コードの読みやすさを向上させるために、必要に応じてドキュメント以外のコメントを使用します。
h. 可能な限り文章ではなくフレーズを使用して、説明内容を簡潔かつ要点に保ちます。
i. グローバル変数、静的変数、および定数は、対応するタグで宣言する必要があります。
7. まとめ
phpDocumentor は非常に強力な自動ドキュメント生成ツールで、標準化されたコメントを作成し、理解しやすく明確な構造のドキュメントを生成するのに役立ちます。これは、コードのアップグレード、メンテナンス、引き継ぎなどに非常に役立ちます。
phpDocumentor の詳細については、公式 Web サイトを参照してください。
http://manual.phpdoc.org/View
8.付録 付録 1:
phpdoc で認識されるキーワード:
含む
必要とする
include_once
一回だけ必要
定義する
関数
グローバル
クラス
付録 2
ドキュメント内で使用できるタグ
<b>
<コード>
<br>
<kdb>
<リ>
<前>
<ul>
<サンプル>
<var>
付録 3:
正規のコメントを含む php コードの一部:
<?php
/**
* サンプル ファイル 2、phpDocumentor クイックスタート
*
* このファイルには、以下に含めることができる豊富な情報が示されています。
* DocBlocks とタグによるコード内ドキュメント。
* @author Greg Beaver < [email protected] >
* @バージョン1.0
* @パッケージサンプル
*/
// サンプルファイル #1
/**
* phpDocumentor の解析能力を示すためのダミーのインクルード値
*/
include_once 'sample3.php';
/**
* 特別なグローバル変数宣言 DocBlock
* @グローバル整数 $GLOBALS['_myvar']
* @name $_myvar
*/
$GLOBALS['_myvar'] = 6;
/**
*定数
*/
/**
* 最初の定数
*/
定義('テスト', 6);
/**
* 2番目の定数
*/
定義('別の定数', strlen('hello'));
/**
* サンプル関数 docblock
* @global string この関数が $_myvar を使用するという事実を文書化します
* @staticvar integer $staticvar これは実際に返されるものです
* @param string $param1 宣言する名前
* @param string $param2 名前の値
* @return 整数
*/
関数 firstFunc($param1, $param2 = 'オプション') {
静的 $staticvar = 7;
グローバル $_myvar;
$staticvar を返します。
}
/**
* 最初のクラス例。これは、
*ファイルの先頭に手続き的なもの
* @パッケージサンプル
* @サブパッケージクラス
*/
クラス myclass {
/**
* プライベート変数のサンプル。これは --parseprivate で非表示にできます。
*オプション
* @accessprivate
* @var 整数|文字列
*/
var $firstvar = 6;
/**
* @link http://www.example.comリンクの例
* @myclass() を参照
* @uses テスト、別の定数
* @var 配列
*/
var $秒変数 =
配列（
「もの」 =>
配列（
6、
17、
'アルマジロ'
）、
テスト => 別の定数
);
/**
* コンストラクターは{@link $firstvar} を設定します
*/
関数 myclass() {
$this->firstvar = 7;
}
/**
* $paramie に基づいてものを返します
* @param boolean $paramie
* @return integer|babyclass
*/
関数parentfunc($paramie) {
if ($paramie) {
6を返します。
} それ以外 {
新しいベビークラスを返します。
}
}
}
/**
* @パッケージサンプル1
*/
class babyclass extends myclass {
/**
* 生命、宇宙、そしてすべてに対する答え
* @var 整数
*/
var $secvar = 42;
/**
※設定値
* @var 配列
*/
var $threevar;
/**
* 親コンストラクターを呼び出し、 {@link $firstvar} をインクリメントします
*/
関数 babyclass() {
親::myclass();
$this->firstvar++;
}
/**
* これは常に myclass を返します
* @param は $parami を無視しました
* @return myclass
*/
関数parentfunc($paramie) {
新しい myclass を返します。
}
}
?>