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

「オブジェクト指向プログラミングは大規模な 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 ショッピング バッグ内のアイテム - それ数量を持つ shopitem です
@Discussion BagItem オブジェクトは、ShopItem も Product も事前に
インスタンス化することなく構築できます
*/
----------------------- -------------------------------------------------- -------

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

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

文書化された関数またはメソッド
メンバー関数またはメソッドは @function タグを使用して文書化されます。

------------------------------------------------ --------------------------------
/*! @function getItemingroup
@abstract は、指定されたグループの Bagitem を取得し、指定された位置
@param groupno int - バッグ内の配送グループの順序位置
@param pos int - グループ内の Bagitem の位置
@result Object - 指定されたグループの指定された位置にある BagItem
または -1 if見つかりませんでした
*/ とまったく同じではないということです
------ -- ------------------------------------------------ -- --------

メソッドを文書化します。

@functionタグは関数を宣言し、その後に関数またはメンバー関数名が続きます。その後、以前と同様に @abstract タグと @Discussion タグを使用できます。ただし、追加のマーカーが 2 つあります。 @param タグは関数のパラメータを記述するために使用されます。最初の単語は変数の名前とみなされ、残りは任意のテキスト記述になります。 PHP は厳密に型指定された言語ではありませんが、必要な変数の型を宣言することをお勧めします。 @resultタグは戻り値を記述するために使用されます。

文書化された変数
変数またはクラス変数は @var タグを使用して記述されます。この表記法では、最初の単語は変数名とみなされ、他の単語は任意のテキスト記述となります。前と同様に、予想される変数の型を書き出すことをお勧めします。すべてのクラス変数を文書化することもお勧めします。


クラス変数を文書化します。

------------------------------------------------ --------------------------------
/*! @var idsession string - 一意のセッション識別子 */
var $セッション
---------------------------------------------- --- ----------------------------------
ラストコンタクト
----------------------- ---------------------------------------------------- ---- ------------------
/*! @header myprojectname
@火星で買い物をするための仮想ストアを抽象化
@Discussion 違い [...]
*/
-- ------------------------------------------- ----- ----------------------------
@header タグは、文書化されている項目またはクラス グループに関する一般的な情報を提供するために使用されます。 @header タグ自体はプロジェクト名の後に続き、@abstract タグと @Discussion タグで補足できます。通常、クラスは異なるファイルに存在するため (ファイルごとに 1 つのクラスがあり、クラスの名前をファイルに付けることをお勧めします)、@header タグをどこに配置するか疑問に思うかもしれません。答えは驚くべきもので、どこにでもあり得るのです。私の提案は、長い説明の場合は別のファイルに置くか、短い説明の場合は最も重要なクラスの前に置くことです。

PHP で使用するためにスクリプトを変更する方法
Apple から入手した初期の HeaderDoc スクリプトは C または C++ ヘッダー ファイル用であるため、PHP で使用するにはいくつかの小さな変更が必要です。詳細に興味がない場合は、ここからダウンロードして残りは飛ばしてください。
ソース プログラムを変更するために必要な唯一のことは、スクリプトがメイン Perl ファイル内の .php および .php3 サフィックスを受け入れるようにすることです。

------------------------------------------------ --------------------------------
$ diff headerDoc2HTML.pl /usr/local/bin/headerdoc2html
195c195
< ; ($rootFileName = $filename) =~ s/.(h|i)$//;
---
> ($rootFileName = $filename) =~ s/.(h|i|php|php3) $//;
-------------------------------------------- --- ----------------------------------
スクリプトを実行します
スクリプトをインストールした後、 class がclasses サブディレクトリにあり、生成されたドキュメントを docs ディレクトリに置きたい場合は、次のコマンドを実行する必要があります:

headerdoc2html -o docsclasses/*.php

残念ながら、複数の PHP ファイルがある場合、このスクリプト A悪い習慣は、これらのファイルを別のディレクトリに分割することです。これにより、クラスのドキュメント内を移動することが困難になります。また、初期スクリプトは C/C++ ヘッダー ファイル用に記述されているため (ヘッダー ファイルにはクラスと関数の宣言のみがあり、その定義はありません)、スクリプトは「;」に遭遇するまで関数名の下にすべてのコードを出力します。 , したがって、通常はコードの最初の行です。

しかし、ここまで進んで絶望する前に、リラックスしてください。両方の問題を解決するための簡単なスクリプトを書いたからです。

------------------------------------------------ --------------------------------
catclasses/*.php sed/*{/;#{ /g' | tr "#" "
" > docs/all.php
headerdoc2html -o docs docs/all.php
rm docs/all.php
-------------- -------------------------------------------------- ----------------
なぜここで sed を使用せずに tr コマンドを使用するのか疑問に思っている方は、その理由は、このコマンドが現在でも使用されている sed 3.02 バージョンで使用されているためです。 RedHat 6.2 では改行は処理されません。新しいバージョン sed 3.02a に置き換える必要があります。 sed に興味がある場合は、SED FAQ をご覧ください。

文書作成の仕事がうまくいくことを祈っています!