開発者にとって、ドキュメントは常に最も厄介なことの 1 つです。さらに、ドキュメントに対して 2 つのまったく異なる態度をとる可能性が非常に高いです:
他人のコード ベースを使用するとき、最も必要なものはその技術ドキュメントです。特に時間が限られており、そうしなければならない場合はそうです。そしてそれらのぎくしゃくしたコードを読んでください。
独自のプログラムを作成するとき、そのための特別な技術文書を作成することは最も避けたいことです。さまざまな理由で自分に言い訳をするでしょう。私のコードは十分に明確であり、文書を書き直す必要はありません。と書かれています...
おそらくこの矛盾を軽減するために、ソース コードから対応するコメントを抽出することで、対応する API ドキュメントを自動的に生成できるツールがたくさんあります。 Javaではjavadoc、Perlではpod2man。対照的に、PHP には以前は対応するツールが不足していたようですが、phpdoc の継続的な改善により、この状況は大幅に改善されました。
最初の pear コーディング ルールには、pear プログラム内のコメントを phpdoc で変換できる必要があるというものがありました。 phpdoc が pear で重要な役割を果たしていることがわかります。今日は、優れた pear プログラムである phpdoc について詳しく説明します。
1. phpdoc とは
PHPDoc は、Javadoc と同様の機能を実現することを目的としており、コードの相互参照、インデックス付け、その他の機能を備えた API ドキュメントを迅速に生成できます。 javadoc によって生成されたドキュメント (jdk ドキュメントなど) を使用したことがある場合は、それをよく知っているでしょう。まだ使用していない場合は、phpdoc で生成されたドキュメント ページのスクリーンショットを次に示します。 phpdoc によって生成されたドキュメントは JAVADOC に非常に似ていることがわかります。これにはさまざまなインデックス付けメソッドがあります。
Packageindex: これはモジュールに従ってインデックス付けされます。
Classtree: これは php クラスの継承関係に基づいており、ツリー状のインデックス
Modulegroups: これはモジュールに従って分割されます
Elementlist: これはすべての要素 (クラス、メソッド、プロシージャ/関数、変数) のアルファベット順のインデックスです
2. phpdoc の構造と機能
phpdoc 自体も pear 準拠のアプリケーションなので、まずその構造を理解しましょう。 phpdoc はすべて OOP アイデアを使用して記述されており、これは PEAR によって推奨されている方法でもあります。
phpdoc は、指定されたディレクトリの下にある php ソース コードをスキャンし、キーワードをスキャンし、分析する必要があるコメントをインターセプトします。コメント内の専用タグを使用してxmlファイルを生成し、解析されたクラスとモジュールの情報をもとに、対応するインデックスを作成し、生成されたxmlファイルをカスタマイズしたテンプレートを使用して出力します。 htmlファイル。
設計上、phpdoc は 2 つのスーパークラス、PhpdocObject と PhpdocError を使用します。これは、PHPDOC 全体の基本クラスであり、PEAR によっても推奨されています。つまり、独自のアプリケーション フレームワークを作成する場合は、基本的なスーパー クラスを作成し、他のサブクラスまたは関数クラスを作成するのが最善です。共通の祖先。ソースコードをスキャンするプロセスでは、PHPDOC は GREP に似た形式を使用しており、通常考えられているような正規表現は使用しません。作者の説明によると、一度正規表現を使用しようとしたものの、リソースが両方とも占有されてしまいました。速度や処理速度を満足させるのが難しいため、この型破りな形式が採用されています。具体的な実装に興味のある読者は、ソースコードを参照してください。 PHPDOC のもう 1 つの満足のいく点は、分析結果が XML 形式で保存されることです。これは、PHPDCO が、API ドキュメントを実装できる対応するインターフェイスも提供していることを意味します。 PDF、LATEX、WORD などの他の形式。現在、PHPDOC の分析結果は HTML 形式で表現できますが、将来的にはさらに多くの形式が追加される可能性があります。 HTML 形式でも、テンプレート メカニズム (PEAR の IT および ITX モジュールを使用して実装) を使用しているため、必要なスタイルに簡単にカスタマイズできます。
3 PHPDoc の基本
PHPDoc はソースから派生します。コードのコメントで生成されるため、プログラムにコメントを付けるプロセスはドキュメントをコンパイルするプロセスでもあります。
この観点から、PHPdoc は、適切なプログラミング習慣を身につけ、仕様書とクリア テキストを使用してプログラムに注釈を付けるよう努めることを推奨します。同時に、ドキュメントの非同期準備やその後のドキュメントの更新を多かれ少なかれ回避します。 。
PHPDoc 仕様に準拠したコメントを準備することは非常に重要です。これをマスターすると、基本的に PHPDoc を使用できるようになります。
PHPDoc では、コメントはドキュメント コメントとドキュメント以外のコメントに分けられます
3.1 ドキュメント コメント
ドキュメント コメントは、実際には特殊な形式の複数行コメントであり、通常はコメントする必要がある特定のキーワード内に配置されます (これらのキーワードは参照先です) phpdoc によって分析されるこれらのキーワード 関連するキーワードのリストについては、以下のセクション 4 の説明を参照してください。以下はドキュメント コメントの例です:
/**
* すべての phpdoc クラスの共通基本クラス (簡単な説明、インデックス リストで使用)
*
* 一種の共通基本クラスとして PhpdocObject が保持します
* 設定値(例: エラー処理) およびデバッグ
* メソッド (例: introspection()) にはコンストラクターがありません
。* これでいつでも Phpdoc クラスを問題なく継承できます
* (詳細な機能説明)
*
* @author Ulf Wendel
* @version $Id: PhpdocObject.php,v 1.3 2001/02/18 15 : 29:29 uw Exp $
* @package PHPDoc (ドキュメント タグ)
*/
class PhpdocObject {
.....
}
上記のドキュメント コメントにより、次のドキュメントが生成されます:
PhpdocObject
すべてのphpdocクラスの共通基本クラス
プライベートクラスPhpdocObject
すべてのphpdocクラスの共通基本クラス
PhpdocObjectが保持する共通基本クラスの一種として設定値 (例: エラー処理) とデバッグ方法 (例: introspection())
コンストラクターがないため、いつでも問題なくこのクラスから Phpdoc クラスを継承できます。 wendel@ phpdoc.de>
バージョン $Id: PhpdocObject.php,v 1.3 2001/02/18 15:29:29 uw Exp $
3.2 ドキュメント以外のコメント
コメントが指定されたコメントに配置されていない場合キーワードの前に phpdoc を追加すると、phpdoc は作成したコメントをドキュメント以外のコメントとみなし、phpdoc によって分析されず、生成する API テキストにも表示されません。
3.3 ドキュメントコメントの書き方
3.1 から、ドキュメントコメントは 3 つの部分、つまり関数概要説明領域、関数詳細説明領域、ドキュメントマーク領域で構成されていることがわかります。
まず、最初の行はコメント開始マーク「/**2 行目からが関数の概要説明エリアです。関数の概要説明エリアはインデントされた「*」で始まり、概要説明の本文と「*」の間はスペースで区切られています。 " 記号 (ドキュメントでは、これらはすべて * で始まり、これらの * は整列したインデント形式を維持していることに注意してください)。関数の説明のテキストは通常、このクラス、メソッド、または関数の機能を簡単に説明し、関数の説明のテキストを示します。ドキュメントはインデックス領域に表示されます。
関数の概要説明領域の後には、関数の概要説明領域と詳細説明領域を区切るために使用される空のコメント行も表示されます。インデント '*' で囲んだ部分です。この部分では主に API の機能と使用法を詳細に説明し、可能であれば使用例なども説明します。このセクションでは、API 関数またはメソッドの一般的な目的と使用法を明確にすることに重点を置き、それがクロスプラットフォームであるかどうか (関係する場合) を示す必要があります。プラットフォーム関連の情報については、一般的な情報とは異なるものとして扱う必要があります。通常のアプローチは、新しい行を開始してから、特定のプラットフォームに関する注意事項や特別な情報を書き込むことです。この情報は、読者が境界条件、パラメーター範囲、ブレークポイントなどの対応するテスト情報を書き込むことができるようにするのに十分です。
関数の詳細な説明領域の後には、空白のコメント行があり、そこに関連するドキュメント マークを記述して、それを示すことができます (これらのドキュメント マークの使用法については、以下のセクション 4 を参照してください)。いくつかの技術的な問題に関する詳細情報。最も重要なのは、呼び出しパラメータのタイプ、戻り値とそのタイプ、継承関係、関連するメソッド/関数などです。読み取りと分析を容易にするために、複数のドキュメント タグは同じインデントを使用して「マーク ブロック」を形成する必要があります。
ドキュメントマーク領域の下の行はコメントの終了行です。」*/」です。コメント終了マーク */ の直後に他のものを追加しないでください。 PHPDOC 解析エラーが発生する可能性があります。
以上がドキュメントコメントの基本的な書き方です。ドキュメントを書く際の仕様やテクニックについてお話します。
3.4 ドキュメント作成ガイド
コードの目的や機能を説明するときは、ほとんどの人の習慣に従うのが最善です。平たく言えば、「あなたが教えてくれた情報は、まさに私が知りたいことです」。この目的のために、ドキュメントのコメントを書くためのヒントと規則をいくつか紹介します。お役に立てば幸いです:
キーワード、名前、および関連コードをマークするには、 を使用します。ドキュメント内でいくつかのキーワードや変数名を引用する必要がある場合、またはいくつかのコード例を示したい場合は、<code> を使用してこれらのキーワード、変数名、コード スニペットを結合し、分離することをお勧めします。読者がそれを読んだときに、これらが説明的な言語ではなく、実行中のコード、キーワードであることがわかるようにドキュメントを作成します。
シンプルで明確な言葉を使用し、長く複雑でわかりにくい文章を説明することは避けてください。特に関数の説明やパラメータの説明などの索引セクションでは、シンプルで明確な言葉を使用して主な情報を明らかにし、その他の詳細は詳細説明セクションに含めるようにしてください。英語を使用する場合は、必ずしも文章ではなくフレーズを使用することをお勧めします。
英語を使用する場合は、三人称単数形を使用して説明することをお勧めします。
メソッドや関数を説明するときは、「方法」ではなく、そのメソッドが「何を行うか」を説明する必要があります。したがって、指示は「レコード数を返す」、「指定されたレコードを削除する」などの動詞で始めることをお勧めします。
参照するオブジェクトまたは変数が現在のクラスから作成されている場合は、そのオブジェクトまたは変数を参照するために「the」の代わりに「this」を使用してください
提供したい API については、「API が必須」に空の単語やナンセンスを避けてください。 「自己文書化」できるように、その背後に機能の説明が含まれています。いわゆる空虚な話とナンセンスとは、あなたの説明が機能の説明ではなく、単に API 名の繰り返しやリスト、またはこの API を説明するために別の API を使用していることを意味します。表現したい内容。説明は、API 名を繰り返すのではなく、クラス名、メソッド名、関数名からはわからない補足情報である必要があります。多くの人が無意識のうちにこの間違いを犯している可能性があります (私も含めて)。以下に例を示します。段落コメント？したがって、関数名からわかるように、このコメントは実際にはナンセンスです。改善されたバージョンは次のとおりです:
/**
* ユーザーレコードセットを設定します
*
* @param text 指定されたテーブル名
*/
function set_user_record($table) {
リンクを適切に使用してください。ドキュメント内で参照されている API 名 (他のクラスやメソッド、PHP 関数などを含む) への適切なリンクを追加することは歓迎されます。@link タグを使用して関連する API へのリンクを追加できますが、その必要はありません。ドキュメント内で参照されているすべての API への接続を追加します。これは見苦しくなります。これは単純な基準です。ユーザーがここに API を見つけた場合、実際にはそれをクリックして詳細情報を取得したいので、ドキュメントを理解できるようにします。また、リンクを追加する場合でも、最初に表示される場合にのみ追加し、同じリンクを繰り返し追加する必要はありません。
PHPDOC の機能制限により、PHP ファイルは 1 つのクラスまたはモジュールのみを定義します。クラスとモジュールの定義を同じファイルに置かないでください。そうしないと、少なくとも現在のバージョンでは PHPDOC が機能しない可能性があります。 OOP を使用してフレームワークを構築する場合は、複数のモジュールまたはモジュール グループを同時に使用しないようにする必要があります。また、アプリケーションのフレームワークは、上部が多すぎないツリー状の構造になるように慎重に計画する必要があります。 -level ブランチ たとえば、通常のアプリケーション用とエラー処理用の 2 つのスーパー クラスを設計でき、残りはこれら 2 つのクラスから派生します。
4. PHPDoc キーワードとドキュメント フラグ
4.1 キーワード
class、function、var、include (include_once、require、require_once)、define
これらのキーワードの前に作成されたコメントはドキュメント コメントとみなされます。
4.2 ドキュメントタグ
説明: 使用範囲は、タグを変更するために使用できるキーワード、または他のドキュメントタグを参照します。
@abstract 使用範囲: class、function、var
現在のクラスが抽象クラスであることを示します。
注: PHP 言語の観点からは、JAVA や C++ のような抽象クラスの概念はサポートされていません。クラスを抽象クラスとして変更するための対応するキーワードはありません。 PHPDOC は実際にほとんどのプラクティスを JAVADOC から借用しているため、abstract、access、final などの多くのドキュメント タグも JAVADOC から直接継承されています。これらの機能は言語レベルではサポートされていませんが、ユーザーの観点からは、これらの機能に従うことをお勧めします。
例:
/**
* システム ユーザー テーブルを開き、現在のユーザー レコード セットとして設定します。このレコード セットは、後続の関連ユーザー データ更新操作のデフォルト レコード セットとして使用されます。失敗するとデータベース エラーがスローされます。
*
* @param text 開かれるシステムユーザーテーブルのテーブル名。
*/
class pattern_start {
/**
* これは 5 つ星のパターンを描画する抽象クラスです
* @abstract
*/
var $number;
/**
* 描画量
* @abstract
*/
function plain() {
;
}
}
@access (public|private) 使用範囲:class、function、var、define、module
この変数、クラス、関数/メソッドのアクセス権を示します。関数が内部で使用される場合は、関数をプライベートとして指定する必要があります。これの利点は、PHP が他の人によるプライベート データの使用を防ぐことができないとしても、少なくともこれがプライベート関数であるという情報をユーザーに伝えることができることです。将来のバージョンに存在することが保証されていないため、ユーザーに対して @private として表されるデータとメソッドは、たとえ使用できたとしても、直接使用しないでください。
例:
/**
* 五つ星模様を描く
* @abstract
* @access public
*/
class pattern_start {
/**
* これは、5 つ星のパターンを描画する抽象クラスです
* @abstract
* @access public
* @access private
*/
var $number;
/**
* 描画量
* @abstract
* @access private
* @access public
*/
function Pain() {
;
}
}
@author Name [
を使用してください著者情報を指定し、その後に著者の名前、電子メール アドレス、その他の通信情報を指定します。複数の作成者がいる場合は、複数の @author を使用して順番にリストします。
* @author Night Sailer
@author Lee Tester
@sister (function()|$variable) 使用範囲: class、function、var、define、module、use
兄弟を指摘するクラス、関数、変数など。これらの関数、クラス、変数などは同様の情報を持ち、同じ機能を実装します。たとえば、呼び出されて返されるパラメータの数と型は同じであり、実装される関数も同じです。この場合、@brother または @sister を使用して兄弟関数を指定することができ、関数や関数のその他の情報を繰り返し記述する必要はありません。
例:
/**
* これは、5 つ星のパターンを描画する抽象クラスです
* @abstract
* @access public
*/
class pattern_start {
/**
* 描画量
* @abstract
* @access private
*/
var $number;
/**
* 五つ星の模様を描く
* @abstract
* @access public
*/
function plain() {
;
}
/**
* @brother ペイント()
*/
functiondraw() {
;
}
}
@const[ant] label [description] 使用範囲: 定義
定数を示す
このラベルは実際には上記は、PHP の定義キーワードによって定義される定数を説明するために使用されます。
@著作権の説明 使用範囲: クラス、関数、変数、モジュール、定義、使用
著作権情報を示します。
@deprec[ated] ラベルの使用範囲: クラス、関数、変数、モジュール、定義、使用
非推奨または廃止された情報を示します。
関数またはメソッドの 1 つが新しい関数メソッドに置き換えられた場合、または放棄されており、読者はそれを使い続けることは期待されていません。次に、このフラグを使用して、この関数が互換性のためにのみ予約されており、その使用が推奨されないことを読者に伝えることができます。別の関数に置き換えられている場合は、その置き換えも示します。
例:
/**
* 廃止されたクラス
*
* @deprec 1.5-2000/12/06
* @access public
*/
function dontUseMeAnyMore() {
print "これ以上私を使用しないでください。私は非推奨になりました。";
}
@exclude ラベルの使用範囲: class、function、var、module、define、use
現在のコメントが分析されず、ドキュメントに表示されないことを示します
@final 使用範囲: class、function、var
これが最終的なクラス、メソッドであることを示します, 属性、派生、改変は禁止されています。
例:
/**
* ピ
* @final
*/
var $PI = 3.1415926;
@global (object objecttype|type) [$varname] [description] 使用範囲: function
この関数内の参照を示しますグローバル変数
例:
/**
* PHP 3 の include_once と同じです。
*
* @global array $__used_files インクルードされるファイルのリスト
* @access public
*/
function include_once($filename) {
global $__used_files;
if (!isset($__used_files["include_once"][$filename])) {
$ __used_files["include_once"][$filename] = true;
include($filename);
}
}
@include description 使用範囲: use
インクルードされたファイルに関する情報を示します。
例:
/**
* 抽象描画クラスの定義。
*
* @includeFunction: _require_
*/
require("abstract.php");
@link URLの説明 使用範囲: class、function、var、module、define、use
オンライン接続の定義、上記の 3.4 で述べたように、@link を使用して適切なオンライン リンクを追加できます。
例: @link http://www.phpdoc.de/ PHPDoc Home
@magic description
このタグはphpdocには記述されておらず、具体的な使い方はまだ不明です
@module label 使用範囲: module
所有権の定義 モジュール情報。ラベルはモジュールの名前です。同じモジュール名を持つ関数はインデックス カテゴリにまとめられます。 OOP アイデアを使用して PEAR コードを作成しない場合は、フレームワーク全体が断片化しすぎて混乱しないように、このタグを使用して関連する関数を対応するモジュールにグループ化することをお勧めします。
@modulegroup label 使用範囲: module
定義されたモジュール グループ ラベルは、このモジュール グループの名前です。アプリケーションに多数のモジュールがある場合、このようにして、異なるモジュールを異なる論理機能に従って対応するモジュール グループに分割できます。を使用すると、アプリケーション フレームワークに明確な論理関係を持たせることができます。これは、OOP プログラミングを使用したことがない人向けです。OOP のアイデアを使用する場合は、「パッケージ-スーパークラス-ベース クラス-サブクラス」の形式を直接使用して反映できるため、モジュール グループの概念を使用する必要はありません。このフレームワークは、「パッケージ-モジュール グループ-モジュール」形式を使用するよりもはるかに優れています。
@package ラベルの使用範囲: クラス、モジュール
所属するパッケージの情報を定義します。label はパッケージの名前です。同じパッケージ名を持つクラスは、最終的なドキュメント インデックスにグループ化されます。実際、パッケージは異なる名前空間として理解することもできます。PHP には名前空間の概念がありませんが、この方法では、関連するクラスとモジュールを同じパッケージに帰属させることができます。もちろん、アプリケーション フレームワークには異なるパッケージが存在する可能性があります。残念ながら、この場合、異なるパッケージ内の関数またはクラスの名前の重複を人為的に回避することしかできません。
@param[eter] (object objecttype|type) [$varname] [description] 使用範囲: function
関数またはメソッドのパラメータ情報を定義します。これは最も一般的に使用されるドキュメント マークアップです。
ojecttype はオブジェクトのクラス名で、type はこのパラメータのタイプを示します。次のタイプが可能です:
string このパラメータは文字変数です。
array このパラメータは配列です。
integer このパラメータは数値型です。
整数 (8 進数) このパラメータは数値型で、8 進数形式で保存されます。
integer (16 進数) このパラメータは数値型であり、16 進形式で保存されます。
boolean このパラメータはブール型です。
混合 このパラメータのタイプは可変であり、上記のタイプを組み合わせることもできます。ただし、受け入れられる変数のタイプは、一般的に以下の説明で説明されます。
$varname は仮パラメータの名前です。
[description] はパラメータの説明です。
関数が複数のパラメータを受け入れる場合は、以下に示すように、@param に合わせて左から右にリストする必要があります:
*
* @param array $tags getTags によって返されるタグの配列
* @param array $data array where許可されたタグとその値がコピーされます
* @param array $allowed 許可された (認識された) タグの配列
@return (object objecttype|type) [$varname] 使用範囲: 関数
を定義します関数またはメソッドの情報を返します。
返される情報のタイプは @param と同じです。$varname は返される変数の名前です (オプション)。違いは、@return が 1 つだけであり、複数の @return
@see (function()|$varname|((module|class)::)(function()|$varname)) [, ... ] 使用範囲: クラス、関数、変数、モジュール、定義、使用
参照する必要がある関数と変数を定義し、対応するハイパーリンクを追加します。これは、より一般的に使用されるタグでもあります。関連する関数および変数については、@see を使用して、関連する関数および変数へのリンクを追加できます。関連する複数の関数と変数は、カンマで区切って 1 行に記述します。
参照される関数または変数が現在のクラスまたはモジュールに属している場合、関数または変数の名前を直接記述することができます。関数の場合は、関数名の後に括弧 () を追加し、変数名に $ を追加します。 。ここでのいわゆる変数名も @var を使用して説明する必要があることに注意してください。そうしないと、phpdoc が関連する参照を見つけられず、エラーが報告されます。
他のクラスや他のモジュールの関数や変数を参照したい場合は、関数名と変数名の前にスコープインジケーターとしてクラスまたはモジュールの名前を追加し、真ん中で::で区切ります。
ここにいくつかの例があります:
@see $run_time,$idle_time,$begin_time,$end_time
@see getRuntime(), getIdletime(),getBegintime(),getEndtime()
@see TIME::$run_time, TIME: :getBegintime()
@since ラベルの使用範囲: クラス、関数、変数、モジュール、定義、使用
API 関数またはメソッドがどのバージョンから導入されたかを示します。
@static 使用範囲: class、function、var
変数、クラス、関数が静的であることを示します。
@throws 例外 [, 例外] 使用範囲: 関数
この関数がスローする可能性のあるエラー例外と、それが発生する状況を示します
この関数に例外を生成する条件があることが予想される場合は、次のように使用できます@throws マーク これらの例外が何であるか、どのような状況で発生するかを説明します。たとえば、ディスク ファイルの読み取りエラー、データベースに接続できないこと、ネットワーク接続のタイムアウト、場合によっては「意図的に」スローした例外などがあります。
@todo 使用範囲: クラス、関数、モジュール、使用
改善すべき部分、または実装しない部分を示します
@var[iable] (object objecttype|type) [$varname] [description] 使用範囲: var
定義の説明 変数/プロパティ。
object objecttype|type は変数のタイプを定義します。@param と同じです。
$varname 変数の名前。@see を使用してこの名前を他の場所から参照できます。
description 変数の説明
@version ラベルの使用法スコープ: クラス、関数、モジュール、使用
バージョン情報を定義する
もちろん、このバージョン情報を手動で記述することもできますが、PEAR では、CVS の $Id タグを使用してバージョン情報を自動的にマークすることをお勧めします。フォームは次のとおりです:
@version $Id
このようにして、チェックアウトすると、CVS は自動的に次のように展開されます: @version $Id: PhpdocParserCore.php,v 1.4 2001/02/18 14:45:27 uw Exp
5 . ドキュメントを生成する
5.1 PHPDOCをインストールする
PHPDOC のインストールは非常に簡単です。PHP 4.05 でリリースされているため、PHP が 4.05 の場合は、PEAR ディレクトリに PHPDOC モジュールが見つからない場合は、コピーを入手できます。 PHPDOC の CVS 最新のソースコード
5.2 PHPDOC の実行
PHPDOC を実行するには、まず、PHP.INI のパラメーターを調整する必要があります。
PHPDOC の実行時間は、通常の PHP アプリケーションよりも長いためです。著者の推奨によれば、PHP.INI で定義されている最大実行時間 (デフォルトは 30 秒): PIII では 60 秒、PII では 120 秒、MMX200 では 240 秒、MMX200 では 480 秒。より低く設定されています。タイムアウトが発生した場合は、これらの値を自分で拡張できます。
php.ini を変更します:
;;;;;;;;;;;;;;;;;;;;;
; リソース制限 ;
;;;;;;;;;;;;; ;;; ;;;;
max_execution_time = 480
memory_limit = 8388608
php.ini を変更したくない場合、または変更する権限がない場合は、set_time_limit() 関数を使用してこの時間を設定できます使用方法は次のとおりです: set_time_limit(480 ); 設定はこの時点から開始され、タイムアウトになるまで 480 秒間実行されます。この関数をindex.phpに追加すると、php.iniを変更するのと同じ効果が得られます。
次に、phpdoc ディレクトリの下にあるindex.php ファイルを変更する必要があります:
// インクルードファイルのあるディレクトリ
define("PHPDOC_INCLUDE_DIR", "c:/www/apache/doc/");
Replace " c: /www/apache/doc/ を phpdoc のディレクトリに変更します
// 重要: これをシステムの改行記号に設定します
define("LINEBREAK", "rn");
これは、を定義する記号です。改行、DOS 以下は改行 + 復帰です。UNIX では復帰だけで十分です。
次に、アプリケーションのカスタマイズ作業を行ってドキュメントを生成します。
// アプリケーションの名前を設定します。
//アプリケーションの名前は、たとえばページのタイトルとして使用されます
$doc->setApplication("PHPDoc");
setApplication() はアプリケーションの名前を設定するために使用されます。PHPDOC をアプリケーションの名前に置き換えます
//. ソース ファイルが存在するディレクトリ:
$doc->setSourceDirectory(PHPDOC_INCLUDE_DIR);
setSourceDirectory() は、アプリケーションの PHP ソース ファイルが存在するディレクトリを設定し、PHPDOC_INCLUDE_DIR を実際のディレクトリに置き換えます。生成されたドキュメントは次のとおりです:
$doc->setTarget(PHPDOC_INCLUDE_DIR."apidoc/");
setTarget() は、API ドキュメントが保存されるディレクトリを設定します。PHPDOC_INCLUDE_DIR を変更します。 「apidoc/」を独自のディレクトリに置き換えます。
// これらのテンプレートを使用します:
$doc->setTemplateDirectory(PHPDOC_INCLUDE_DIR."renderer/html/templates/");
setTemplateDirectory() は HTML で使用されるテンプレートを設定します。カスタマイズされたテンプレートを使用する必要がある場合は、この関数を使用して、独自のテンプレート ファイルが配置されるディレクトリを設定できます。
// ソース ファイルには次のいずれかのサフィックスが付いています:
$doc->setSourceFileSuffix( array ("php", "inc") );
setSourceFileSuffix() は、必要な PHP ソース ファイルの拡張子を設定するために使用されます。別の拡張子を使用する場合は、ここに追加する必要があります。たとえば、以前の php3 ファイルがある場合は、
$doc->setSourceFileSuffix( array ("php", "inc") を追加する必要があります。 , "php3") );
これで、基本的なカスタマイズ作業が完了しました。ウェルカム メッセージが表示されたら、マシンの状態に応じてドキュメントの分析を開始します。ドキュメントの分析が完了すると、ブラウザには分析が完了したことを示す「FINISH」という文字が表示されます。 HTML ファイルと XML ファイルを含む分析結果を指定したディレクトリに保存します。
5.3 ユーティリティ ツール
PHPDOC の INDEX.PHP を通じてドキュメントを生成することもできますが、結局のところ、ここではシェル プログラム makeapidoc を紹介します。これを使用すると、毎回変更する必要がなく、ブラウザを起動して実行する必要もなく、便利に API ドキュメントを生成できます。
使い方は以下の通りです: makeapidoc -t アプリケーションのタイトル -s ソースプログラムディレクトリ -d 生成されたドキュメント格納ディレクトリ
使用前に以下の2行を変更してください:
PHPDOC_DIR="/usr/local/lib/php/pear /PHPDoc" # windows: c:/php/pear/PHPDoc
PHPBIN="/usr/local/bin/php" #windows: c:/php/php.exe
PHPDOC_DIR は PHPDOC のディレクトリ、PHPBIN はディレクトリここで、PHP は実行可能ファイルへのパスを指定できます。
このプログラムは実際には PHP を SHELLSCRIPT として使用しますが、BASH に埋め込まれています。実際には、PHP は -q パラメーターを追加するだけで通常の SHELL スクリプトとして実行できるため、HTTP ヘッダーは出力されません。
6. 詳細: 出力ドキュメントをカスタマイズする
デフォルトの PHPDOC で生成された HTML ドキュメントが十分に美しくなく、さらに改善したい場合、たとえば、一部のコメントを中国語または他のテキストに変更したい、ロゴや連絡先情報を追加したい、などの場合は、それを美しい背景パターンに変更する方法はありますか? 答えはもちろん非常に簡単です。
PHPDOC は API ドキュメントを HTML 形式で出力するときに PEAR モジュールを使用します。したがって、PHPLIB の TEMPLETE.CLASS を使用すると、ニーズに合わせてデフォルトのテンプレートを簡単にカスタマイズおよび変更できます
まず PHPDOC/renderer/html/templates を見てみましょう: class.html classtree.html elementlist.html Frame_packageelementlist.html
Frame_packagelist.html module.html modulegroup.html packagelist.html phpdoc.css warnings.html xmlfiles.html
上記のファイルが表示されます。はい、これらは PHPDOC が API HTML を生成するために使用するテンプレートです。これでエディターを使用できるようになります。これらのテンプレートを変更するための基本的な変更原則は次のとおりです:
{} で囲まれたタグについては、PHPDOC は実行時に実際の変数の値を使用し、対応する位置に置き換えられます。すべての変数タグを保持する必要があります。そうしないと、実行時にエラーが発生します。 に注意してください。 LOOP を含むコメントの場合、これら 2 つのタグの間の部分がループ出力に使用されるため、テンプレートをデザインするときは、ループの使用によってページの美しさが損なわれないかどうかを考慮する必要があります。最も単純な例: ループ部分が にある場合。テーブルの場合は、 を使用して各ループ呼び出しの部分を区切る必要があり、各 が一致して閉じられていることを確認する必要があります。スタイル シート phpdoc.css の内容を直接変更することもできます。これにより、テンプレートを別のディレクトリに保存し、setTemplateDirectory() を通じて別のテンプレート パスを設定することもできます
。 7. 参照リソース
PHPDOC HOME
PHPDOC CVS
![[Web フロントエンド] Node.js クイック スタート](https://img.php.cn/upload/course/000/000/067/662b5d34ba7c0227.png)
