PHP ドキュメント コード コメント仕様_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. グローバル変数、静的変数、および定数は、対応するタグで記述する必要があります
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 とタグを通じて * コード内ドキュメントに含めることができる豊富な情報を示します。

* @著者 Greg Beaver <[email]celllog@php.net[/email]>

* @バージョン 1.0
* @パッケージサンプル
*/
// サンプルファイル #1
/**
* phpDocumentor の解析能力を示すためのダミーのインクルード値
*/
include_once 'サンプル3.php';
/**
* 特別なグローバル変数宣言 DocBlock
* @global integer $GLOBALS['_myvar']
* @name $_myvar
*/
$GLOBALS['_myvar'] = 6;
/**
* 定数
*/
define('テスト', 6);
/**
* 最初の定数
*/
define('anotherconstant', strlen('hello'));
function firstFunc($param1, $param2 = 'オプション') {
static $staticvar = 7;
return $staticvar;
/**
* 2 番目の定数
*/
var $firstvar = 6; /**
* サンプル関数 docblock
* @global string この関数が $_myvar を使用するという事実を文書化します
* @staticvar integer $staticvar これは実際に返されるものです
* @param string $param1 宣言する名前
* @param string $param2名前の値
* @return integer
*/
var $secondvar =
array(
'stuff' =>
array(
6,
17,
'armadillo'
),
testing => anotherconstant
/ **
* 最初のクラス例。これは、ファイルの先頭にある
* 手続き型のものと同じパッケージ内にあります
* @package サンプル
* @subpackage クラス
*/
function myclass() {
$this->firstvar = 7;
/**
* プライベート変数のサンプル。これは --parseprivate
* オプションで非表示にすることができます
* @accessprivate
* @var integer|string
*/
functionparentfunc($paramie) {
if ($paramie) {
return 6;
} else {
return new babyclass
}
}
}
/**
* @link http://www.example.com リンク例
* @see myclass()
* @uses testing, anotherconstant
* @var array
*/
class babyclass extends myclass {
/**
* コンストラクターは {@link $firstvar} をセットアップします
*/
var $secondvar = 42; /**
* $paramie に基づいてものを返します
* @param boolean $paramie
* @return integer|babyclass
*/
var $thirdvar;
/**
* @パッケージサンプル1
*/
function babyclass() {
$this->firstvar++;
/**
* 生命、宇宙、そしてすべてに対する答え
* @var integer
*/
functionparentfunc($paramie) {
新しい myclass を返す
}
}

;



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

www.bkjia.com

tru​​e

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

技術記事

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