PDP ドキュメント コード コメント仕様ページ 1/2_PHP チュートリアル

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 install PhpDocumentor
b． 手動インストール
PhpDocumentor の最新バージョン (現在 1.4.0) を http://manual.phpdoc.org/ からダウンロードし、コンテンツを解凍します。

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 形式の場合、デフォルトの名前は document.pdf と表示されます。

4. PHP コードに標準化されたコメントを追加します

PHPDocument はソース コードのコメントからドキュメントを生成するため、プログラムにコメントを付けるプロセスはドキュメントをコンパイルするプロセスでもあります。 この観点から、PHPdoc は、良いプログラミング習慣を身につけ、仕様書とクリア テキストを使用してプログラムに注釈を付けるよう努めることを奨励します。同時に、ドキュメントの準備とドキュメント間の同期が失われる問題を多かれ少なかれ回避します。その後ドキュメントを更新します。 phpdocumentor では、コメントはドキュメントコメントと非ドキュメントコメントに分けられます。
いわゆるドキュメントコメントは、特定のキーワードの前に配置される複数行のコメントです。特定のキーワードとは、class、var など、phpdoc で解析できるキーワードを指します。詳細については、付録 1 を参照してください。キーに含まれていない 単語の前にあるコメント、または標準化されていないコメントは非ドキュメント コメントと呼ばれ、これらのコメントは phpdoc によって分析されず、生成する API ドキュメントには表示されません。
3.2 ドキュメント コメントの書き方:
すべてのドキュメント コメントは /** で始まる複数行のコメントであり、phpDocumentor では DocBlock と呼ばれます。これは、ソフトウェア開発者が作成した特定のキーワードに関するヘルプ情報を指します。このキーワードの具体的な目的と使用方法を理解してください。 PhpDocumentor では、DocBlock に次の情報が含まれることが規定されています:
1. 関数の簡単な説明領域
2. 詳細な説明領域
ドキュメントのコメントの最初の行は、一般的にクラスとその内容を説明します。簡潔なメソッドまたは関数の関数、関数の簡単な説明のテキストが、生成されたドキュメントのインデックス領域に表示されます。関数説明領域の内容は、空白行で終了することもできます。
関数説明領域の後には、詳細な説明領域が続きます。この部分では、主に API の機能と目的を詳細に説明します。使用例なども教えていただけます。このセクションでは、API 関数またはメソッドの一般的な目的と使用法を明確にすることに重点を置き、それがクロスプラットフォームであるかどうか (関係する場合) を示す必要があります。プラットフォーム関連の情報については、一般的な情報とは異なるものとして扱う必要があります。通常のアプローチは、新しい行を開始してから、特定のプラットフォームに関する注意事項や特別な情報を書き込むことです。この情報は、読者が境界条件、パラメーター範囲、ブレークポイントなどの対応するテスト情報を書き込むことができるようにするのに十分です。
その後に空行があり、ドキュメントタグがあり、主に呼び出しパラメータの型、戻り値と型、継承関係、関連するメソッド/関数などの技術情報を示します。
ドキュメントのマーキングについては、セクション 4: ドキュメントのマーキングを参照してください。
ドキュメントのコメントで などのタグを使用することもできます。詳細については、付録 2 を参照してください。
以下はドキュメントコメントの例です

コードをコピーします コードは次のとおりです:

/**
* 関数 add、2 つの数値の加算を実装します
*
* 単純な加算計算、関数は 2 つの数値 a、b を受け入れ、それらの合計 c を返します
*
* @param int 加数
* @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
作成者を示します
@copyright
使用範囲: class、 function 、 var、define、 module、use
著作権情報を示します
@deprecated
使用範囲: class、function、var、define、 module、constent、global、include
未使用または廃止されたキーワードを示します
@example
このタグは Parse で使用されていますファイルの内容を強調表示します。 Phpdoc は、このタグで指定されたファイル パスからファイルの内容を読み取ろうとします
@const
スコープの使用:define
php で定義された定数の指定に使用されます
@final
スコープの使用:class、function、var
キーワードが最終的なクラス、メソッド、および属性は派生または変更することが禁止されています。
@filesource
例と似ていますが、このタグは現在解析されている php ファイルの内容を直接読み取って表示する点が異なります。
@global
この関数で参照されるグローバル変数を示します
@ingore
ドキュメント内の指定されたキーワードを無視するために使用されます
@license
HTML タグの に相当し、最初に URL が表示され、次に表示されますコンテンツ
たとえば、Baiduは、@license http://www.baidu.com Baidu
@link
と同様に記述できます。ライセンスを取得するには
ただし、リンク
@name を通じてドキュメント内のキーワードを指定することもできます
キーワードのエイリアスを指定します。
@package
使用範囲: ページ レベル -> 定義、関数、インクルード
クラス レベル -> クラス、変数、メソッド
1 つまたは複数のキーワードを論理的にグループ化するために使用されます。
@abstrcut
現在のクラスが抽象クラスであることを示します
@param
関数のパラメータを指定します
@return
メソッドまたは関数のリターンポインタを指定します
@static
キーワードが静的であることを指定します
@var
変数の型を示します
@version
バージョン情報を示します
@todo
改善すべき領域または実装されていない領域を示します
@throws
この関数がスローする可能性のあるエラー例外と極端な状況を示します
前述のように、通常の文書タグは各行の先頭に @ を付ける必要があります。さらに、{@} で表されるインライン タグと呼ばれるタグもあり、次の種類があります。
{@link}
使用方法は次のとおりです。 @linkと同じ
{@source}
関数やメソッドの内容を表示
6．一部のコメント仕様
a. コメントは
/**
* XXXXXXX
*/ の形式でなければなりません
b. グローバル変数を参照する関数の場合は、glboal タグを使用する必要があります。
c. 変数の場合、その型は var (int、string、bool...) でマークされる必要があります。
d. 関数は、param および return マーカーを通じてパラメータを指定する必要があります。他の関数またはクラスが呼び出される場合、ドキュメントを読みやすくするために、リンクまたは他のタグを使用して対応する部分にリンクする必要があります。
g. コードの読みやすさを向上させるために、必要に応じてドキュメント以外のコメントを使用します。
h. 可能な限り文章ではなくフレーズを使用して、説明内容を簡潔かつ要点に保ちます。
i. グローバル変数、静的変数、および定数は、対応するタグで宣言する必要があります



http://www.bkjia.com/PHPjc/319862.html

www.bkjia.comtru​​ehttp://www.bkjia.com/PHPjc/319862.html技術記事 1. phpDocumentor とは何ですか? PHPDocumentor は、PHP で書かれたツールで、標準のアノテーションを備えた PHP プログラムに対して、相互参照、インデックス作成、その他の機能を備えた API ドキュメントを迅速に生成できます。古い...