phpdocの紹介

コアポイント

• phpdoc（phpdocumentor）は、開発者が特別な形式の注釈を介してコードドキュメントを作成するのに役立つ強力なツールです。 HTML、PDF、CHMなどの複数の形式でドキュメントを生成できます。これは、Webインターフェイスまたはコマンドラインインターフェイスを介して抽出できます。
• PHPDOCは、Docblocks（マルチラインCスタイルのコメント）を使用してコードブロックを文書化します。 docblocksには、短い説明、詳細な説明、タグの3つのオプションパーツが含まれています。タグは、コードに関する追加情報を指定する@シンボルから始まります。
• PHPDOCパッケージは、生成されたドキュメントに関連するコード要素をグループ化するために使用されます。ファイルレベルまたはクラスレベルのDocblockで@packageおよび@subpackageタグを使用して、ファイルとクラスのパッケージを指定できます。
• phpdocは、ファイル、クラス、関数、メソッド、クラスプロパティ、グローバル変数、include()/require()、define()など、さまざまなコード要素のドキュメントを記述できます。これらの要素は特定の一般的なタグを使用できますが、それぞれに特定のタグがあります。
• PHPDOCのコマンドラインツールは、記述されたPHPコードに基づいてユーザーフレンドリーなドキュメントを生成するために使用されます。このツールは、さまざまなドキュメント形式を提供します。コマンドラインインターフェイスに精通していないユーザーには、PHPDOCもWebインターフェイスを提供します。

他の人によって書かれたコードを読むこと（誰がそれを経験していないのですか？）は難しい作業です。乱雑な「パスタスタイルのコード」は、多数の奇妙な名前の変数と混合されており、めまいがします。この関数は文字列または配列を期待していますか？この変数は整数またはオブジェクトを保存しますか？数え切れないほどのコード追跡と各部分の機能を理解しようとした後、コード全体をゼロからあきらめて書き直すことが一般的です。それはあなたの貴重な時間の無駄です。 PHPDOC（PHPDocumentorのショート名）は、特別な形式でコメントを含むコードドキュメントを簡単に書き込むことができる強力なツールです。ドキュメントは、ソースコードだけでなく、Webインターフェイスまたはコマンドラインインターフェイスを介して抽出された専門ドキュメントも利用できます。結果は、HTML、PDF、CHMなどのさまざまな形式になります。さらに、コードの完了を提供する多くのIDEは、PHPDOCのコメントを解析し、タイププロンプトなどの実用的な機能を提供できます。 phpdocを使用することで、他の人（および自分自身）がコードを簡単に理解できるようにすることができます。 PHPDOCをインストールする最も簡単な方法は、梨を使用することです。もちろん、あなたがそうする前に梨を設置する必要があります。洋ナシがインストールされていない場合は、pear.php.net/manual/en/installation.phpの指示に従ってください。この記事では、PHPDOCで最初から最後まで美しくユーザーフレンドリーなドキュメントを生成する方法を紹介します。

docblocks

docblockは、コードブロックのドキュメントを作成するために使用されるマルチラインCスタイルのコメントです。それは/**で始まり、各ラインにアスタリスクがあります。例は次のとおりです。

<?php
/**
 * 计算数组中每个元素的平方和
 *
 * 循环遍历数组中的每个元素，将其平方，并将其添加到总和中。返回总和。
 *
 * 此函数也可以使用 array_reduce() 实现；
 *
 * @param array $arr
 * @return int
 * @throws Exception 如果数组中的元素不是整数
 */
function sumOfSquares($arr) {
    $total = 0;
    foreach ($arr as $val) {
        if (!is_int($val)) {
            throw new Exception("Element is not an integer!");
        }
        $total += $val * $val;
    }
    return $total;
}

docblocksには、短い説明、詳細な説明、ラベルの3つの部分が含まれています。 3つの部分はすべてオプションです。簡単な説明は、新しいラインまたはピリオドで終わる簡潔な説明です。 PHPDOCの分析ルーチンは、期間が文の終わりにある場合にのみ、短い説明で終了します。詳細な説明は、ドキュメントの主なコンテンツです。詳細な説明と短い説明の両方に、フォーマットのための特定のHTML要素を含めることができます。サポートされていないHTMLタグは、プレーンテキストとして表示されます。 PHPDOCは複数の形式でドキュメントを生成できます。そのため、HTMLタグは、実際の形式が生成されたドキュメントの形式に依存するように、必ずしもレンダリングしません。 HTMLタグをテキストとして表示する必要がある場合は、ダブルブラケットを使用してください。たとえば、

<?php
/**
 * 这里是斜体标签的示例： >Hello, world!>
 */

docblockのタグセクションには、@シンボルで表される特別なタグが任意の数に含まれています。タグは、予想されるパラメーターやそのタイプなどの追加情報を指定するために使用されます。ほとんどのタグは独自の行にある必要がありますが、一部のタグにはインラリングできます。インラインタグは巻き毛装具に囲まれており、詳細な説明と簡単な説明で表示できます。タグの完全なリストについては、関連するPHPDOCドキュメントをご覧ください。 @シンボルから始めるために行が必要であるが、それをラベルとして解釈したくない場合は、バックスラッシュで逃げることができます。 PHPDOCは、詳細な説明と短い説明でテキストリストを自動的に識別して解析します。ただし、ネストされたリストを正しく解析しません。ネストされたリストを使用する場合は、HTMLタグを使用します。私が意味することを説明する例は次のとおりです。

<?php
/**
 * 使用列表的示例
 *
 * PhpDoc 将正确解析此列表：
 * - 项目 #1
 * - 项目 #2
 * - 项目 #3
 *
 * 但不是这个列表：
 * - 项目 1
 *   - 项目 1.1
 *   - 项目 1.2
 * - 项目 2
 *
 * 请改用此方法创建嵌套列表：
 * 

*

项目 1

*

*

项目 1.1

*

项目 1.2

* *

项目 2

* */

（スペースの制限と主要な情報の保持により、次のコンテンツが簡単に要約されます）bag

PHPDOCパッケージは、生成されたドキュメントに関連するコード要素をグループ化するために使用されます。これらのパッケージを継承するために書かれたコードを含むファイルとクラスのパッケージを指定できます。パッケージを指定するには、ファイルレベルまたはクラスレベルのDocblockにタグを設定します。 （ファイルレベルおよびクラスレベルのドックブロックについては、次のセクションでさらに説明します）。パッケージ名には、文字、数字、ダッシュ、アンダースコア、および四角いブラケット（ "["および "]）を含めることができます。ファイルパッケージを定義する方法の例は次のとおりです。

複数のレベルのパッケージとサブパッケージがある場合は、@packageタグを使用してサブパッケージを定義できます。例は次のとおりです。

<?php
/**
 * 这是一个文件级 DocBlock
 *
 * @package Some_Package
 */

ファイルまたはクラスがパッケージを指定していない場合、デフォルトのパッケージ「デフォルト」に設定されます。 @subpackageコマンドラインオプションを使用して、デフォルトで使用する他のパッケージを指定できます。

<?php
/**
 * 这是一个类级 DocBlock
 *
 * @package    Some_Package
 * @subpackage Other
 */
class SomeClass {
}

どの文書を書くことができますか？ -dn

すべてのコード要素がdocblocksを使用して記述できるわけではありません。これは、ドキュメントに記述できるコード要素のリストです。

• ファイル
• カテゴリ
• 関数と方法
• class属性
• グローバル変数
• include()/require()
• define()

これらの要素はすべて特定の一般的なラベルを使用できますが、各要素にはその要素に固有のラベルがあります。通常、ドキュメントを書くために使用される要素とタグをいくつかカバーします。

（ファイル、クラス、関数、メソッドのドキュメントの例は簡単になりますが、キータグの説明のみが保持されます）

ドキュメントを生成

PHPコードのドキュメントを書いた後、ユーザーフレンドリーなドキュメントを生成する必要があります。これを行うには、PHPDOCコマンドラインツールを実行します。

<?php
/**
 * 计算数组中每个元素的平方和
 *
 * 循环遍历数组中的每个元素，将其平方，并将其添加到总和中。返回总和。
 *
 * 此函数也可以使用 array_reduce() 实现；
 *
 * @param array $arr
 * @return int
 * @throws Exception 如果数组中的元素不是整数
 */
function sumOfSquares($arr) {
    $total = 0;
    foreach ($arr as $val) {
        if (!is_int($val)) {
            throw new Exception("Element is not an integer!");
        }
        $total += $val * $val;
    }
    return $total;
}

（コマンドラインパラメーターの説明は簡単になります）

概要

この記事では、PHPDOCとその多くの強力な機能を紹介します。 Docblocksとそのコンポーネントの目的を説明しました。最も重要な部分のドキュメントを書いているだけであっても、自分のプロジェクトでPHPDOCの使用を開始することを強くお勧めします。それは非常にシンプルで、あなたとあなたの同僚が数え切れないほどの緊張と痛みを救うことができます。

（FAQセクションは簡単に、コア質問と短い回答を保持します）

以上がphpdocの紹介の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。