PHPドキュメント生成ツールについて

1. phpDocumentor とは何ですか?

PHPDocumentor は、標準のアノテーションを備えた 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.2) を http://manual.phpdoc.org/ からダウンロードし、コンテンツを解凍します。

3. PhpDocumentor を使用してドキュメントを生成する方法

a. コマンド ライン メソッド

phpDocumentor が配置されているディレクトリで、

Php -h

と入力すると、次のようないくつかの重要なパラメーターのリストが表示されます。 -f 続行するには 分析対象のファイル名、複数のファイルはカンマで区切ります

-d 分析対象のディレクトリ、複数のディレクトリはカンマで区切ります

-t 生成されたドキュメントの保存パス

-o 出力ドキュメント形式の場合、構造は出力形式 : コンバータ名: テンプレート ディレクトリです。

例: phpdoc -o HTML:frames:earthli -f test.php -t docs

b. Web インターフェイスの生成

新しい phpdoc では、コマンドラインでドキュメントを生成するだけでなく、ドキュメントを参照することもできます。クライアント上でサーバー上で操作してドキュメントを生成します。 具体的な方法は、まず PhpDocumentor のコンテンツをブラウザからアクセスできるようにすることです。 アクセス後、次のインターフェイスが表示されます。ファイル ボタンをクリックして、処理する PHP ファイルまたはフォルダーを選択することもできます。このインターフェイスで無視するファイルを指定することによって、特定のファイルの処理を無視することもできます。

次に、出力ボタンをクリックして、生成されるドキュメントの保存パスと形式を選択します。

最後に作成をクリックすると、phpdocumentor が自動的にドキュメントの生成を開始します。成功した場合は、生成の進行状況とステータスが下部に表示されます。 ,

Total Documentation が表示されます 時間: 1 秒

done

Operation Completed!!

その後、生成されたドキュメントを表示できます。PDF 形式の場合、名前はデフォルトで document.pdf になります。

c. phpdocumentor を試してみる

以下では、phpdocumentor を使用してドキュメントを生成する方法を例として、pear の phpunit2 を取り上げます。

まず、必要なパラメータを決定します:

-d

c:/program files/easyphp5/php/pear/phpunit2

-t

c:/program files/easyphp5/php/phpunit2doc

-o

html:frames:phpedit

上記のパラメータに従って、次のコマンドを組み合わせます:

phpdoc -d "c:/program files/easyphp5/php/pear/phpunit2" -t "c :/program files/easyphp5/php/phpunit2doc" -o "html:frames:phpedit"

上記のコマンドを実行すると、phpdocumentor がソースファイルの解析を開始し、作品情報を出力します。

コマンドが完了すると、ドキュメントが生成されました。指定したターゲット ディレクトリを入力し、ブラウザでindex.htmlを開いて、生成されたドキュメントを確認します。ドキュメントインターフェイスはフレームによって 3 つの部分に分かれており、左上がパッケージ情報、左下がナビゲーション情報、右が詳細情報の表示ページです。

インデックス、関数リスト、クラスリスト、ファイルリスト、サブパッケージ。上のクラスのリンクをクリックすると、パッケージ全体のクラス ツリーが明確に表示されます。いずれかのクラスをクリックすると、クラスの説明ページが表示されます。クラス説明ページには主に次の側面が含まれます:

[説明: 著作権、作成者、クラス階層など]、[クラス変数]、[クラス定数]、[メソッド]、[継承変数]、[継承メソッド:とても便利な機能】

どうですか、とても詳しいですね？ chm を生成したい場合は、前の -o パラメータを「chm:default:default」に変更すると、phpdocumentor が chm プロジェクト ファイルを生成し、Microsoft の chm ツールを使用してコンパイルし、使用可能な chm ファイルを取得します。 。

d. 中国語の文字化けの解決策

コメントが中国語の場合、PhpDocumentor/phpDocumentor/Converters/* 内の対応するテンプレートの言語タグを iso-8859-1 から utf-8 に置き換える必要があります。そうでない場合は、生成されたコードが文字化けしてしまいます。

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

PHPDocument はソース コード内のコメントからドキュメントを生成するため、プログラムにコメントするプロセスはドキュメントをコンパイルするプロセスでもあります。この観点から、PHPdoc は、適切なプログラミング習慣を身につけ、仕様書とクリア テキストを使用してプログラムに注釈を付けるよう努めることを奨励します。同時に、ドキュメントの準備とドキュメントの間の非同期の問題を多かれ少なかれ回避します。その後のアップデート。 phpdocumentor では、コメントはドキュメント コメントとドキュメント以外のコメントに分類されます。いわゆるドキュメントコメントは、特定のキーワードの前に配置される複数行のコメントです。特定のキーワードとは、class、var など、phpdoc で分析できるキーワードを指します。詳細については、付録 1 を参照してください。キーワードの前にないコメント、または標準化されていないコメントは非ドキュメント コメントと呼ばれ、これらのコメントは phpdoc によって分析されず、生成する API ドキュメントには表示されません。

ドキュメントコメントの書き方:

すべてのドキュメントコメントは/**最初の複数行のコメントは、phpDocumentor では DocBlock と呼ばれます。DocBlock は、他の人がこのキーワードの具体的な目的とその使用方法を知ることができるように、ソフトウェア開発者によって作成された特定のキーワードに関するヘルプ情報を指します。 PhpDocumentor では、DocBlock に次の情報が含まれると規定しています:

1. 関数の簡単な説明領域

2. 詳細な説明領域

ドキュメントのコメントの最初の行は関数の説明領域です。一般に簡潔な説明 このクラス、メソッドまたは関数の関数、および関数の簡単な説明のテキストが、生成されたドキュメントのインデックス領域に表示されます。関数記述領域の内容は空行または「.」で終了することができます。関数の説明領域の後には空白行があり、その後に詳細な説明領域が続きます。この部分では主に API の機能と目的を詳細に説明します。可能であれば使用例なども含めます。このセクションでは、API 関数またはメソッドの共通の目的と使用法を明確にすることに重点を置き、それがクロスプラットフォームであるかどうか (関係する場合) を示す必要があります。通常のアプローチは、新しい行を開始して、特定のプラットフォームに関する注意事項や特別な情報を書き込むことです。この情報は、読者が境界条件、パラメーター範囲、ブレークポイントなどの対応するテスト情報を書き込むのに十分なはずです。 。その後に空白行があり、ドキュメントタグがあり、主に呼び出しパラメータの型、戻り値と型、継承関係、関連するメソッド/関数などの技術情報を示します。

ドキュメントのマークアップについては、詳細については -- ドキュメントのマークアップ を参照してください。 などのタグもドキュメントのコメントで使用できます。詳細については、付録 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

Parameters

? int $a - addend

? int $b - summand

5 を返します。ドキュメント タグ:

ドキュメント タグの使用範囲は、タグを使用して変更できるキーワードまたはその他のドキュメント タグを指します。すべてのドキュメント タグは、各行の * の後に @ で始まります。 @マークが段落の途中にある場合、通常の内容として扱われ無視されます。

@access

使用範囲: class、function、var、define、module

このタグは、キーワード: private、public、または protected のアクセス許可を示すために使用されます

@author

使用範囲: class、function、 var,define,module,use

作者を示す

@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

に似ていますが、リンク

を通じてドキュメント内のキーワードをポイントすることもできます

@name

キーワードのエイリアスを指定します。

@package

使用範囲: ページレベルのdefine、関数、include

クラスレベルのclass、var、メソッド

1つまたは複数のキーワードを論理的にグループにグループ化するために使用されます。

@abstrcut

現在のクラスが抽象クラスであることを示します

@param

関数のパラメータを示します

@return

メソッドまたは関数の戻りポインタを示します

@static

キーワードは静的です。

@var

変数の型を示します

@version

バージョン情報を示します

@todo

改善すべき領域または実装されていない領域を示します

@throws

この関数が発生する可能性のあるエラー例外を示します極端な場合にはスローします

上で述べたように、通常のドキュメント タグは各行の先頭に @ を付ける必要があります。さらに、{@} で表されるインライン タグと呼ばれるタグもあり、これには具体的には次のものが含まれます。

{@link}

使い方は@linkと同じです

{@source}

関数やメソッドの内容を表示します

6．一部のコメント仕様

a. コメントは

/**

* XXXXXXX

*/

の形式でなければなりません b. グローバル変数を参照する関数の場合は、glboal タグを使用する必要があります。

c. 変数の場合、その型 (int、string、bool...) は var

d でマークされなければなりません。関数は、param および return マーカー

e を介してそのパラメーターを示す必要があります。キーワードが複数回ある場合は、冗長なものは inore によって無視され、1 つだけが保持される必要があります

f 他の関数またはクラスが呼び出される場合は、リンクまたは他のタグを使用して対応する部分にリンクする必要があります。文書の読み取り。

g. コードの読みやすさを向上させるために、必要に応じてドキュメント以外のコメントを使用します。

h. 可能な限り文章ではなくフレーズを使用して、説明内容を簡潔かつ要点に保ちます。

i. グローバル変数、静的変数、および定数は、対応するタグで記述する必要があります

7. 概要

ドキュメントを書くのは面倒ですが必要な作業であり、API レベルのドキュメントを書くのは多くの労力と一貫性の維持を意味します。 。ここでみなさんにおすすめしたいのが、php5構文解析に対応したドキュメントツール-phpDocumentorです。 phpDocumentor は非常に強力な自動ドキュメント生成ツールで、標準化されたコメントを作成し、理解しやすく明確な構造のドキュメントを生成するのに役立ちます。これは、コードのアップグレード、メンテナンス、引き継ぎなどに非常に役立ちます。 phpDocumentor を使用すると、コードから関数とメソッドの定義を自動的に抽出できるだけでなく、さまざまなクラス間の関係を自動的に処理し、それに応じてクラス ツリーを生成できます。ドキュメントを html、chm、または pdf に生成することも選択できます。 phpDocumentor を使用すると、文書化作業がはるかに簡単になります。 phpDocumentor の詳細については、公式 Web サイト http://manual.phpdoc.org/ で確認できます。