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

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

[br]
著者: stefano Locati 翻訳: limodou

文書化された関数またはメソッド
メンバー関数またはメソッドは @function を使用します マークアップは文書化されています。

------------------------------------------ ------ ------------------------------------
/*! getItemingroup
@abstract は、指定されたグループと指定された位置の Bagitem を取得します
@param groupno int - バッグ内の配送グループの順序位置
@param pos int - グループ内の Bagitem の位置
@result Object - 指定されたグループの指定された位置にある BagItem
、または見つからなかった場合は -1
*/
--------------- ------ -------------------------------------------- ------ ---------

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

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

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


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

------------------------------------------ ------ ------------------------------------
/*! idsession 文字列 - 一意のセッション識別子 */
var $idsession>----------------------------- ---------------------------------------------------- ----
最後の連絡
------------------------------------- ------------------------ ------------------------ -------
/*! @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)$//;
---------------------- ------ -------------------------------------------- ------ -
スクリプトを実行します
スクリプトをインストールした後、クラスがクラス サブディレクトリに配置され、生成されたドキュメントを docs ディレクトリに配置したい場合は、次のコマンドを実行する必要があります:

headerdoc2html -o docsclasses/*.php

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

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

------------------------------------------ ------ ------------------------------------
猫クラス/*。 php | sed 's/ *{/;#{/g' | tr "#" "
" > docs docs/all.php
rm docs/ all.php
-------------------------------------- ------ ----------------------------------
なぜ私がそうするのか知りたいならここでは sed を使用する代わりに tr コマンドを使用してください。その理由は、RedHat 6.2 でまだ使用されている sed 3.02 バージョンが改行を処理しないためです。新しいバージョン sed 3.02a に置き換える必要があります。 sed に興味がある場合は、SED FAQ をご覧ください。

文書化作業の成功を祈っています。

翻訳:
この記事は Linux 環境で使用されているため、Windows で使用すると問題が発生する可能性があります。方法が思いついたら考えてみますが、本当に思いつかない場合はどうすることもできません。

原著者: limodou
出典: PHPX