PDP 文書コード コメント仕様 ページ 1/2

1. phpDocumentor とは何ですか?
PHPDocumentor は、PHP プログラムで標準のアノテーションを使用して、相互参照、インデックス付け、その他の機能を備えた API ドキュメントを迅速に生成できるツールです。旧バージョンは phpdoc でしたが、1.3.0 からは phpDocumentor に名前が変更されました。同時に、クライアントのブラウザ上でドキュメントを生成し、ドキュメントを phpDocumentor に変換できるようになりました。 PDF、HTML、CHM にはいくつかの形式があり、非常に便利です。
PHPDocumentor が動作すると、指定されたディレクトリの下にある PHP ソース コードをスキャンし、キーワードをスキャンし、分析が必要なコメントをインターセプトし、コメント内の特別なタグを分析して XML ファイルを生成し、それに基づいて分析されたクラスとモジュール情報、対応するインデックスの確立、xml ファイルの生成、およびカスタマイズされたテンプレートを使用して、生成された xml ファイルの指定された形式でファイルを出力します。
2. phpDocumentor をインストールします
pear の他のモジュールと同様に、phpDocumentor のインストールも自動インストールと手動インストールに分かれています。
a ． pear を介して自動的にインストールします
コマンド ラインで入力します
pear install 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 が自動的にドキュメントの生成を開始し、生成の進行状況とステータスが下部に表示されます。成功すると、「
Total Documentation Time: 1 秒」と表示されます。
done
Operation Completed!!
その後、生成されたドキュメントが PDF 形式の場合、名前はデフォルトで表示されます。ドキュメント.pdf。

4． PHP コードに標準化されたコメントを追加する PHPDocument はソース コードのコメントからドキュメントを生成するため、プログラムにコメントするプロセスはドキュメントをコンパイルするプロセスでもあります。
この観点から、PHPdoc は、適切なプログラミング習慣を身につけ、仕様書とクリア テキストを使用してプログラムに注釈を付けるよう努めることを奨励します。同時に、ドキュメントの非同期開発やその後のドキュメントの更新を多かれ少なかれ回避します。いくつかの質問。
phpdocumentor では、コメントはドキュメント コメントとドキュメント以外のコメントに分けられます。
いわゆるドキュメント コメントは、特定のキーワードの前に配置される複数行のコメントです。特定のキーワードとは、class、var など、phpdoc で分析できるキーワードを指します。詳細については、付録 1 を参照してください。
キーワードの前にないコメント、または標準化されていないコメントは非ドキュメント コメントと呼ばれ、これらのコメントは phpdoc によって分析されず、生成する API ドキュメントには表示されません。
3.2 ドキュメント コメントの書き方:
すべてのドキュメント コメントは /** で始まる複数行のコメントであり、phpDocumentor では DocBlock と呼ばれます。DocBlock はソフトウェア開発者によって作成された重要なコメントを指します。キーワードを使用すると、他の人がこのキーワードの具体的な目的とその使用方法を知ることができます。 PhpDocumentor では、DocBlock に次の情報が含まれると規定しています。
1. 関数の簡単な説明領域
2. マーク タグ
ドキュメント コメントの最初の行は、関数の説明領域です。テキストは通常​​、このクラス、メソッド、または関数の関数を簡単に説明します。関数の簡単な説明のテキストは、生成されたドキュメントのインデックス領域に表示されます。関数説明領域の内容は、空白行で終了することもできます。
関数説明領域の後には、詳細な説明領域が続きます。この部分では、主に API の機能と目的を詳しく説明します。可能であれば、使用例なども教えていただければ幸いです。このセクションでは、API 関数またはメソッドの一般的な目的と使用法を明確にすることに重点を置き、それがクロスプラットフォームであるかどうか (関係する場合) を示す必要があります。プラットフォーム関連の情報については、一般的な情報とは異なるものとして扱う必要があります。通常のアプローチは、新しい行を開始してから、特定のプラットフォームに関する注意事項や特別な情報を書き込むことです。この情報は、読者が境界条件、パラメーター範囲、ブレークポイントなどの対応するテスト情報を書き込むことができるようにするのに十分です。
の後にも空行があり、その後にドキュメント タグがあり、主に呼び出しパラメーターの型、戻り値と型、継承関係、関連するメソッド/関数などの技術情報を示します。
ドキュメントタグについては、セクション 4: ドキュメントタグを参照してください。
ドキュメントのコメントで などのタグを使用することもできます。詳細については、付録 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 - 加数
• int $b - 加数
5.ドキュメント タグ:
ドキュメント タグの使用範囲は、タグを使用して変更できるキーワードまたはその他のドキュメント タグを指します。
すべてのドキュメント タグは、各行の * の後に @ で始まります。 @マークが段落の途中にある場合、通常の内容として扱われ無視されます。
@access
使用範囲: class、function、var、define、module
このタグは、キーワードのアクセス許可を示すために使用されます: private、public、または protected
@author
author
@copyright
使用範囲: class、function、var、define、module、use
著作権情報を示します
@deprecated
使用範囲: class、function、var、define、module、 constent 、 global、 include
未使用または廃止されたキーワードを示します
@example
このタグは、ファイル コンテンツの一部を解析し、それらを強調表示するために使用されます。 Phpdoc は、このタグで指定されたファイル パスからファイルの内容を読み取ろうとします
@const
Usingscope:define
php での定義の定数を示すために使用されます
@final
Usingscope : class ,function,var
は、キーワードが最終的なクラス、メソッド、または属性であることを示し、派生と変更が禁止されています。
@filesource
例と似ていますが、このタグが現在解析されている PHP ファイルの内容を直接読み取って表示する点が異なります。
@global
この関数で参照されるグローバル変数を示します
@ingore
は、ドキュメント内の指定されたキーワードを無視するために使用されます
@license
は、HTML タグの < に相当します;a>、最初に URL、次に表示するコンテンツ
たとえば、Baidu は次のように記述できます。 @license http://www.baidu.com Baidu
@link
ライセンス
と似ていますが、リンク
@name
キーワードを指定してドキュメント内のキーワードを指定することもできますエイリアス。
@package
使用範囲: ページ レベル -> 定義、関数、インクルード
クラス レベル -> クラス、変数、メソッド
は 1 つまたは複数のキーワードを論理的に組み合わせるために使用されます グループに割り当てられます。
@abstrcut
現在のクラスが抽象クラスであることを示します
@param
関数のパラメータを指定します
@return
メソッドまたは関数の戻りポインタを指定します
@static
Guan Jianzi が静的であることを示します。
@var
変数の型を示します
@version
バージョン情報を示します
@todo
改善すべき領域または実装しない領域を示します
@throws
それを示しますこの関数はエラー例外をスローする可能性があり、非常にまれです。
上記のように、通常のドキュメント タグは各行の先頭に @ を付ける必要があります。さらに、{@} 式を使用するインライン タグと呼ばれるタグもあります。
{@link}
使い方は @link と同じです
{@source}
関数またはメソッドの内容を表示します

6.一部のコメント仕様 a. コメントは
/**
* XXXXXXX
*/

b. グローバル変数を参照する関数の場合は、glboal タグを使用する必要があります。
c. 変数の場合、その型は var (int、string、bool...) でマークされる必要があります。
d. 関数は、param および return マーカーを通じてそのパラメーターと戻り値を示す必要があります。 2 回以上使用されるキーワードについては、冗長なものは inore によって無視され、1 つだけが保持される必要があります。
f 他の関数またはクラスが呼び出される場合は、link または他のタグを使用して対応する部分にリンクする必要があります。文書化を容易にするため。
g. コードの読みやすさを向上させるために、必要に応じてドキュメント以外のコメントを使用します。
h. 可能な限り文章ではなくフレーズを使用し、説明内容は簡潔かつ要点を絞ったものにしてください。
i. グローバル変数、静的変数、および定数は、対応するタグ
で宣言する必要があります。