PHP ドキュメントコードコメント仕様_PHP チュートリアル-PHPチュートリアル-php.cn

PHP ドキュメントコードコメント仕様_PHP チュートリアル

WBOY

リリース： 2016-07-21 15:47:06

オリジナル

716 人が閲覧しました

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. グローバル変数、静的変数、および定数は、対応するタグで記述する必要があります
7. 概要
phpDocumentor は、標準化されたコメントを記述し、理解しやすいドキュメントを生成するのに役立ちます。コードのアップグレード、メンテナンス、引き継ぎなどに非常に役立ちます。
phpDocumentor の詳細な手順については、公式 Web サイト
http://manual.phpdoc.org/ をご覧ください。
8.付録
付録1:
phpdocで認識できるキーワード:
Include
Require
include_once
require_once
define
function
global
class
付録2tagsドキュメント内で使用できます
< ;b> ;

規範的なコメントを含む段落 PHP コード:

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

/*** サンプルファイル 2、phpDocumentor クイックスタート * * このファイルは、DocBlock とタグを通じて * コード内ドキュメントに含めることができる豊富な情報を示します。