PDP 文書コード コメント仕様

1. phpDocumentor とは何ですか?
PHPDocumentor は、PHP で書かれたツールで、標準のアノテーションを備えた PHP プログラムに対して、相互参照、index などの機能を備えた API ドキュメントを迅速に生成できます。旧バージョンは phpdoc でしたが、1.3.0 からは phpDocumentor に名前が変更されました。同時に、クライアントのブラウザ上でドキュメントを生成し、ドキュメントを phpDocumentor に変換できるようになりました。 PDF、HTML、CHM にはいくつかの形式があり、非常に便利です。
PHPDocumentor が動作すると、指定されたディレクトリの下にある PHP ソース コードをスキャンし、キーワードをスキャンし、分析が必要なコメントをインターセプトし、コメント内の特別なタグを分析し、XML ファイルを生成し、分析された内容に基づいてクラスとモジュールの情報を取得し、対応する index を確立し、生成された 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. 詳細な説明領域
3. 関数の関数、関数の簡単な説明のテキストが
index
領域に表示されます。生成されたドキュメント内。関数説明領域の内容は、空白行で終了することもできます。
関数説明領域の後には、詳細な説明領域が続きます。この部分では、主に 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
このタグを使用ファイルの内容を解析して強調表示します。 Phpdoc は、このタグで指定されたファイル パスからファイル の内容を読み取ろうとします @const
スコープを使用します:define
PHP で定義された定数を指定するために使用されます
@final
スコープを使用します: class、function、var
キーワードを指定しますは最終的なクラス、メソッド、および属性であり、派生または変更することは禁止されています。
@filesource
例と似ていますが、このタグは現在解析されている php ファイルの内容を直接読み取って表示する点が異なります。
@global
この関数で参照される
グローバル変数を示します@ingore
は、ドキュメント内の指定されたキーワードを無視するために使用されます
@license
HTMLタグのと同等で、最初にURL、次にコンテンツです。表示されます
たとえば、
Baiduは @license http://www.baidu.com
Baidu と書くことができます @link
license
と似ていますが、link を通じてドキュメント内のキーワードを指定することもできます
@name
キーワードのエイリアスを指定します。
@package
使用範囲: ページレベル -> 定義、関数、
include クラスレベル -> クラス、変数、メソッド
1 つまたは複数のキーワードを論理的にグループにグループ化するために使用されます。
@abstrcut
現在のクラスが抽象クラスであることを示します
@param
関数のパラメータを示します
@return
メソッドまたは関数の戻りポインタを示します
@static
キーワードが静的であることを示します
@var
変数の型を示します
@version
バージョン情報を示します
@todo
改善すべき領域、または実装されていない領域を示します
@throws
この関数がスローする可能性のあるエラー例外と極端な状況を示します
前述のように上記のように、通常の文書タグは各行の先頭に @ を付ける必要があります。また、{@} で表されるインライン タグと呼ばれるタグもあり、次の種類があります。
{@link}
の使用方法。 @linkと同じ
{@source}
関数やメソッドの内容を表示
6．一部のコメント仕様
a. コメントは
/**
* XXXXXXX
*/
の形式でなければなりません
b.
グローバル変数 を参照する関数の場合は、glboal タグを使用する必要があります。 c. 変数の場合、その型 (int、string、bool...) は var
d でマークする必要があります。関数は、2 回出現する変数の場合は、パラメーターと戻り値のマーカー
e を使用する必要があります。他の関数またはクラスが呼び出される場合、ドキュメントを読みやすくするために、リンクまたは他のタグを使用して対応する部分にリンクする必要があります。
g. コードの読みやすさを向上させるために、必要に応じてドキュメント以外のコメントを使用します。
h. 可能な限り文章ではなくフレーズを使用して、説明内容を簡潔かつ要点に保ちます。
i.
グローバル変数
、静的変数、および定数は、対応するタグで記述する必要があります7. 概要phpDocumentor は、標準化されたコメントを記述し、わかりやすい構造を生成するのに役立つ非常に強力なドキュメント自動生成ツールです。明確なドキュメントは、コードのアップグレード、メンテナンス、引き継ぎなどに非常に役立ちます。
phpDocumentor の詳細な手順については、公式 Web サイト
http://manual.phpdoc.org/
8 で確認できます。付録
付録1:
phpdocで認識できるキーワード:
include
require
include_once
require_once
define
function
global
class
付録2
で使用できるタグドキュメント

エンディックス3 :
正規のコメントを含む php コードの一部
/**
* サンプル ファイル 2、phpDocumentor クイックスタート
*
* このファイルは、DocBlocks とタグを通じてコード内ドキュメントに
含め
* できる豊富な情報を示しています。
* @author Greg Beaver * @バージョン 1.0* @パッケージサンプル*/
// サンプル ファイル #1
/**
* phpDocumentor
の解析能力を示すためのダミーの
include
値*/

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


上記では、require、include、グローバル変数、注意事項、Baidu のコンテンツなど、PDP ドキュメントのコードのコメント仕様を紹介しています。PHP チュートリアルに興味のある友人の参考になれば幸いです。