コアポイント

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

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

docblocks

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

<?php
/**
 * 計(jì)算數(shù)組中每個(gè)元素的平方和
 *
 * 循環(huán)遍歷數(shù)組中的每個(gè)元素，將其平方，并將其添加到總和中。返回總和。
 *
 * 此函數(shù)也可以使用 array_reduce() 實(shí)現(xiàn)；
 *
 * @param array $arr
 * @return int
 * @throws Exception 如果數(shù)組中的元素不是整數(shù)
 */
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には、短い説明、詳細(xì)な説明、ラベルの3つの部分が含まれています。 3つの部分はすべてオプションです。簡(jiǎn)単な説明は、新しいラインまたはピリオドで終わる簡(jiǎn)潔な説明です。 PHPDOCの分析ルーチンは、期間が文の終わりにある場(chǎng)合にのみ、短い説明で終了します。詳細(xì)な説明は、ドキュメントの主なコンテンツです。詳細(xì)な説明と短い説明の両方に、フォーマットのための特定のHTML要素を含めることができます。サポートされていないHTMLタグは、プレーンテキストとして表示されます。 PHPDOCは複數(shù)の形式でドキュメントを生成できます。そのため、HTMLタグは、実際の形式が生成されたドキュメントの形式に依存するように、必ずしもレンダリングしません。 HTMLタグをテキストとして表示する必要がある場(chǎng)合は、ダブルブラケットを使用してください。たとえば、

<?php
/**
 * 這里是斜體標(biāo)簽的示例： >Hello, world!>
 */

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

<?php
/**
 * 使用列表的示例
 *
 * PhpDoc 將正確解析此列表：
 * - 項(xiàng)目 #1
 * - 項(xiàng)目 #2
 * - 項(xiàng)目 #3
 *
 * 但不是這個(gè)列表：
 * - 項(xiàng)目 1
 *   - 項(xiàng)目 1.1
 *   - 項(xiàng)目 1.2
 * - 項(xiàng)目 2
 *
 * 請(qǐng)改用此方法創(chuàng)建嵌套列表：
 * 

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

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

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

<?php
/**
 * 這是一個(gè)文件級(jí) DocBlock
 *
 * @package Some_Package
 */

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

<?php
/**
 * 這是一個(gè)類(lèi)級(jí) DocBlock
 *
 * @package    Some_Package
 * @subpackage Other
 */
class SomeClass {
}

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

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

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

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

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

ドキュメントを生成

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

<?php
/**
 * 計(jì)算數(shù)組中每個(gè)元素的平方和
 *
 * 循環(huán)遍歷數(shù)組中的每個(gè)元素，將其平方，并將其添加到總和中。返回總和。
 *
 * 此函數(shù)也可以使用 array_reduce() 實(shí)現(xiàn)；
 *
 * @param array $arr
 * @return int
 * @throws Exception 如果數(shù)組中的元素不是整數(shù)
 */
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;
}

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

概要

この記事では、PHPDOCとその多くの強(qiáng)力な機(jī)能を紹介します。 Docblocksとそのコンポーネントの目的を説明しました。最も重要な部分のドキュメントを書(shū)いているだけであっても、自分のプロジェクトでPHPDOCの使用を開(kāi)始することを強(qiáng)くお?jiǎng)幛幛筏蓼?。それは非常にシンプルで、あなたとあなたの同僚が?shù)え切れないほどの緊張と痛みを救うことができます。

以上がphpdocの紹介の詳細(xì)內(nèi)容です。詳細(xì)については、PHP 中國(guó)語(yǔ) Web サイトの他の関連記事を參照してください。