PHP クラスを文書化する方法 (1)_PHP チュートリアル

PHP クラスを文書化する方法 (1)


著者: stefano Locati 翻訳: limodou


You have read about: オブジェクト指向プログラミングは大規模な Web プロジェクトの管理に役立ちます、そしてあなたは PHP を使い始めましたオブジェクト指向プログラミングをやったことがありますか? Web サイトで使用するいくつかのクラスを作成し、組織化された人であれば、それらについてのドキュメントを作成しているはずです。ただし、私のようなカジュアルな人の場合は、他のドキュメントを必要とせずに、クラスのソース コードにコメントを追加するだけです。ドキュメントがなければ、メソッドの名前とその使用方法 (パラメーターと意味) を覚えるのは困難です。この状況に対する最も一般的な解決策は、ソース コード ファイルを開いて、数百または数千のステートメントを検索することです。


Javadoc のようなドキュメント

良い方法があるはずです。Java 言語を使用したことがあるなら、Javadoc ドキュメント システムを知っているでしょう。このツールを使用すると、ソース コード ファイルのコメントにタグを挿入できます。これを Javadoc ツールで分析して、クラスを文書化するための一連の HTML ページを生成できます。こうすることで、プログラミング中にブラウザを開いて、クラスのリストと説明付きのクラス メソッドのリストを取得できます。 Webアプリケーションを開発する際の参考となり、作業効率の向上や開発のスピードアップにつながります。


私の意見は、参照ドキュメントをソース コード内で参照として維持する方が、別のドキュメントを維持するよりも簡単で、より実用的である、というのがこの方法の方が更新し続けるのが容易だからです。そうしないと、怠けてドキュメントの更新を無期限に延期してしまいがちです (期限を設けるとしたら 10,000 年だと思います)。このようなツールを使用する代わりに、変更するソース コードの近くのタグを更新し、ツールを再度実行して更新された HTML ページを生成するだけです。


いくつかの php ドキュメント ツールのプレビュー

上記を理解した後、利用可能なものを探したところ、次の興味深いツールを見つけました:


phpSearchdoc は酵素プロジェクトの一部です。酵素は大規模なプロジェクトであるため、文書化する必要があります。そこの開発者は独自のドキュメント システムを作成し、それをスタンドアロン パッケージとしてリリースするのに十分寛大です。作成されたドキュメントはまずデータベースに書き込まれ、その後、動的 Web サイトなどの PHP スクリプトで表示できます。


分析用のロジックを既存の情報から分離するというアイデアは非常に優れていますが、phpSearchdoc (バージョン 1.01) には実際のアナライザーがありませんが、ソース ファイルからキーワードを検索し、コメントも検索します。実際、私のコメントの 1 つに「関数」という単語が含まれていたことが起こり、パーサーは愚かにもこの単語に続く単語が関数の名前であると考えました。さらに残念なことに、たまたま同じ行に一重引用符 (') を入れてしまい、データをデータベースに書き込もうとしたところ、mysql からエラーが発生しました ( mysql では文字列を区切るために一重引用符が使用されているため、エラーが発生しました)。


そして、まだアルファテスト版なので、インストールして実行するのはかなり難しいです。結局のところ、これはドキュメント システムというよりも相互参照ジェネレーターであり、私が知っているように、関数やメソッドに独自のコメントを追加することはできません。


phpxrefは、その名前が示すように、実際のドキュメントシステムというよりも相互参照生成プロセスに似ているようです。さらに、オブジェクト指向プログラミングよりも通常の手続き型プログラミングに適しています。


phpautodocの目標は、JavadocがJavaで使用されるのと同じように、PHPで使用されることです。私のドキュメントのニーズにとって完璧なソリューションのように思えました。ジェネレーターは PHP で書かれているため、テストするには PHP の CGI バージョンをコンパイルする必要がありました (通常はモジュール バージョンを使用します)。これらのコマンドを使用すると、静的実行可能ファイルを Linux システムに簡単にコンパイルしてインストールできます:


rm config.chche

make clean

./configure

make

cp php /usr/local/ bin


独自の PHP ソース コードでテストしてみたところ、部分的にしか機能しなかったことがわかりました。クラスのドキュメント (きちんとした形式で) のみ生成できましたが、概要は生成できませんでした。これが私のマシンでたまたま起こったのかどうかはわかりませんが、概要を生成しようとするとコアダンプで停止しました（PHP 4.0 pl2、RedHat 6.2環境）。 PHP 実行可能バージョンが machine/usr/local/bin にインストールされている場合、それを呼び出す構文は次のとおりです (結果を取得するには、php ファイルと出力ディレクトリのフル パスを指定する必要があります)


./ phpautodoc -o


phpdoc は Web サイト上で保守するために使用される php ファイルであり、分散開発に非常に適しています。ドキュメントはデータベースから生成されます。インストール後、Web インターフェイスを使用してクラスを追加し、ドキュメントを作成できます。これは確かに興味深いですが、ドキュメントとソース コードを分離する低レベルのメンテナンス方法であり、私にとってはあまり便利ではありません。


ユニバーサルツール

Pear プロジェクトが標準ソリューションを思いつくまで、これらすべてのツールを試してもあまり成功せずに挫折した後、Apple サイトの Open Source Projects で PHP とはまったく関係のない実用的なツールを見つけました。プロジェクトの名前は HeaderDoc です。サイトにあるように、「HeaderDoc は、C または C++ ヘッダー ファイルのコメントから HTML リファレンス ドキュメントを生成するツールです。移植性を高めるために Perl で書かれています。JavaDoc と同様に、開発者はインターフェイスを簡単に文書化し、インターフェイス情報を出力できます。 HTML "


はい、お読みのとおり、HeaderDoc は C と C++ のみをサポートします。他の言語ではありませんが、JavaDoc とは異なり、主にコメントに記述されたマークアップに依存しているため、いくつかの小さな変更を加えるだけで PHP とうまく連携できます (これについては後ほど説明します)。これらのタグは JavaDoc に非常に似ています。HeaderDoc タグの例としては、@class、@function、@var などがあります。


クラスの文書化

それでは、詳細を見ていきましょう。まず、クラスがどのように文書化されるかを見てみましょう。


---------------------------------------------- --- ----------------------------------

/*! @class BagItem

@abstract Anショッピング バッグ内のアイテム - それは数量を持つ shopitem です

@Discussion BagItem オブジェクトは、ShopItem も Product も事前に

インスタンス化することなく構築できます

*/

----------- ---------------------------------------------------- --------------------


クラスを文書化します。左フレームでクラスメソッドを選択できます。


最初に注意すべきことは、コメントを開くために使用されるスタイルは JavaDoc コメント /** (1 つのスラッシュと 2 つのアスタリスク) とまったく同じではなく、/* (1 つのスラッシュ、1 つのアスタリスク、および感嘆符) に置き換えられていることです。 ）。タグの使用法も異なりますが、同様に機能します。たとえば、最初のタグは @class タグで、クラスを文書化するために使用されます。このタグの後にクラスの名前が続きます。次のタグは @abstract タグです。これはクラスの意味を数語で説明するオプションのタグであり、@Discussion タグはさらなる議論に使用されるもう 1 つのオプションのタグです。もちろん、すべてを @Discussion タグで記述するか、@abstract を使用して処理するかを決定するのはあなた次第ですが、一般に、使用するタグが正確であればあるほど、より良い結果が得られることに留意してください。


原著者: limodou

出典: PHPX

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