核心要點(diǎn)

• PhpDoc (PhpDocumentor) 是一款強(qiáng)大的工具，通過(guò)特殊格式的注釋幫助開(kāi)發(fā)者編寫(xiě)代碼文檔。它能生成多種格式的文檔，例如 HTML、PDF 和 CHM，可以通過(guò) Web 界面或命令行接口提取。
• PhpDoc 使用 DocBlocks（多行 C 風(fēng)格注釋）來(lái)為代碼塊編寫(xiě)文檔。DocBlocks 包含三個(gè)可選部分：簡(jiǎn)短描述、詳細(xì)描述和標(biāo)簽。標(biāo)簽以 @ 符號(hào)開(kāi)頭，用于指定有關(guān)代碼的附加信息。
• PhpDoc 包用于在生成的文檔中對(duì)相關(guān)的代碼元素進(jìn)行分組。可以使用文件級(jí)或類(lèi)級(jí)的 DocBlock 中的 @package 和 @subpackage 標(biāo)簽為文件和類(lèi)指定包。
• PhpDoc 可以為各種代碼元素編寫(xiě)文檔，包括文件、類(lèi)、函數(shù)和方法、類(lèi)屬性、全局變量、include()/require() 和 define()。這些元素可以使用某些通用標(biāo)簽，但也各自擁有特定標(biāo)簽。
• PhpDoc 的命令行工具用于根據(jù)已編寫(xiě)文檔的 PHP 代碼生成用戶友好的文檔。該工具提供多種文檔格式。對(duì)于不熟悉命令行界面的用戶，PhpDoc 還提供 Web 界面。

閱讀他人編寫(xiě)的代碼（誰(shuí)沒(méi)經(jīng)歷過(guò)？）是一項(xiàng)艱巨的任務(wù)。雜亂的“意大利面條式代碼”與大量奇怪命名的變量混雜在一起，令人頭暈?zāi)垦?。這個(gè)函數(shù)期望的是字符串還是數(shù)組？這個(gè)變量存儲(chǔ)的是整數(shù)還是對(duì)象？經(jīng)過(guò)無(wú)數(shù)小時(shí)的代碼追蹤和試圖理解每個(gè)部分的功能后，放棄并從頭重寫(xiě)整個(gè)代碼是很常見(jiàn)的——這浪費(fèi)了您寶貴的時(shí)間。PhpDoc（PhpDocumentor 的簡(jiǎn)稱）是一個(gè)強(qiáng)大的工具，允許您通過(guò)特殊格式的注釋輕松編寫(xiě)代碼文檔。文檔不僅可在源代碼中獲得，還可通過(guò) Web 界面或命令行接口提取的專業(yè)文檔中獲得。結(jié)果可以是多種格式，例如 HTML、PDF 和 CHM。此外，許多提供代碼完成功能的 IDE 可以解析 PhpDoc 注釋并提供類(lèi)型提示等實(shí)用功能。通過(guò)使用 PhpDoc，您可以使其他人（以及您自己）更容易理解您的代碼——即使是在編寫(xiě)代碼幾周、幾個(gè)月甚至幾年之后。最簡(jiǎn)單的 PhpDoc 安裝方法是使用 PEAR。當(dāng)然，在您這樣做之前，必須安裝 PEAR。如果您沒(méi)有安裝 PEAR，請(qǐng)按照 pear.php.net/manual/en/installation.php 上的說(shuō)明進(jìn)行操作。在本文中，我將向您展示如何使用 PhpDoc 從頭到尾生成精美且用戶友好的文檔。

DocBlocks

DocBlock 是一種用于為代碼塊編寫(xiě)文檔的多行 C 風(fēng)格注釋。它以 /** 開(kāi)頭，每行開(kāi)頭都有一個(gè)星號(hào)。這是一個(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;
}

DocBlocks 包含三個(gè)部分：簡(jiǎn)短描述、詳細(xì)描述和標(biāo)簽。所有三個(gè)部分都是可選的。簡(jiǎn)短描述是一個(gè)簡(jiǎn)潔的描述，以換行符或句點(diǎn)結(jié)尾。PhpDoc 的解析例程很智能；只有當(dāng)句點(diǎn)位于句尾時(shí)，它才會(huì)結(jié)束簡(jiǎn)短描述。詳細(xì)描述是文檔的主要內(nèi)容；它可以是多行的，并且可以任意長(zhǎng)。詳細(xì)描述和簡(jiǎn)短描述都可以包含某些 HTML 元素以進(jìn)行格式化。不支持的 HTML 標(biāo)簽將顯示為純文本。PhpDoc 可以生成多種格式的文檔，因此 HTML 標(biāo)簽不一定像在 HTML 文件中那樣呈現(xiàn)；實(shí)際格式取決于生成的文檔格式。如果您需要將 HTML 標(biāo)簽顯示為文本，請(qǐng)使用雙括號(hào)。例如：

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

DocBlock 的標(biāo)簽部分包含任意數(shù)量的以 @ 符號(hào)表示的特殊標(biāo)簽。標(biāo)簽用于指定附加信息，例如預(yù)期的參數(shù)及其類(lèi)型。大多數(shù)標(biāo)簽必須位于它們自己的行上，但某些標(biāo)簽可以內(nèi)聯(lián)。內(nèi)聯(lián)標(biāo)簽用花括號(hào)括起來(lái)，可以出現(xiàn)在詳細(xì)描述和簡(jiǎn)短描述中。有關(guān)標(biāo)簽的完整列表，請(qǐng)查看相關(guān)的 PhpDoc 文檔。如果您需要以 @ 符號(hào)開(kāi)頭一行，但又不想將其解釋為標(biāo)簽，則可以使用反斜杠將其轉(zhuǎn)義。PhpDoc 將自動(dòng)識(shí)別詳細(xì)描述和簡(jiǎn)短描述中的文本列表，并對(duì)其進(jìn)行解析。但是，它不會(huì)正確解析嵌套列表。如果您想使用嵌套列表，請(qǐng)使用 HTML 標(biāo)簽。以下是一個(gè)示例，說(shuō)明我的意思：

<?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)建嵌套列表：
 * 

(以下內(nèi)容因篇幅限制，將簡(jiǎn)略概括，保留關(guān)鍵信息)

包

PhpDoc 包用于在生成的文檔中對(duì)相關(guān)的代碼元素進(jìn)行分組。您可以為文件和類(lèi)指定包，它們包含的已編寫(xiě)文檔的代碼將繼承這些包。要指定包，請(qǐng)?jiān)谖募?jí)或類(lèi)級(jí) DocBlock 中設(shè)置 @package 標(biāo)簽。（文件級(jí)和類(lèi)級(jí) DocBlocks 將在下一節(jié)中進(jìn)一步討論）。包名稱可以包含字母、數(shù)字、短劃線、下劃線和方括號(hào)（“[”和“]”）。以下是如何定義文件包的示例：

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

如果您有多個(gè)級(jí)別的包和子包，則可以使用 @subpackage 標(biāo)簽定義子包。這是一個(gè)示例：

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

如果文件或類(lèi)未指定包，則它將設(shè)置為默認(rèn)包“default”。您可以通過(guò) -dn 命令行選項(xiàng)指定要默認(rèn)使用的其他包。

可以編寫(xiě)哪些文檔？

并非所有代碼元素都可以使用 DocBlocks 編寫(xiě)文檔。以下是可以編寫(xiě)文檔的代碼元素列表：

• 文件
• 類(lèi)
• 函數(shù)和方法
• 類(lèi)屬性
• 全局變量
• include()/require()
• define()

所有這些元素都可以使用某些通用標(biāo)簽，但每個(gè)元素都有特定于該元素的標(biāo)簽。我將介紹一些元素和通常用于為其編寫(xiě)文檔的標(biāo)簽。

(文件、類(lèi)、函數(shù)和方法的文檔編寫(xiě)示例將被簡(jiǎn)略，只保留關(guān)鍵標(biāo)簽說(shuō)明)

生成文檔

編寫(xiě)完 PHP 代碼的文檔后，您需要從中生成用戶友好的文檔。為此，請(qǐng)運(yùn)行 PhpDoc 命令行工具。

<?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;
}

(命令行參數(shù)說(shuō)明將被簡(jiǎn)略)

對(duì)于不熟悉命令行界面的用戶，PhpDoc 還提供 Web 界面。本文檔不詳細(xì)討論它，但您可以在 PhpDoc 的官方網(wǎng)站 phpdoc.org 上了解更多信息。

總結(jié)

在本文中，我向您介紹了 PhpDoc 及其許多強(qiáng)大的功能。我已經(jīng)解釋了 DocBlocks 的用途及其組成部分；我已經(jīng)向您展示了如何使用包來(lái)組織您的文檔；我已經(jīng)解釋了哪些代碼元素可以編寫(xiě)文檔以及一些常見(jiàn)的示例；最后，我已經(jīng)向您展示了如何根據(jù)您的源代碼生成文檔。我強(qiáng)烈建議您在自己的項(xiàng)目中開(kāi)始使用 PhpDoc，即使只是編寫(xiě)最重要的部分的文檔。它非常簡(jiǎn)單，可以為您和您的同事節(jié)省無(wú)數(shù)小時(shí)的緊張和痛苦。

(FAQ 部分將被簡(jiǎn)略，保留核心問(wèn)題和簡(jiǎn)短答案)

以上是PHPDOC簡(jiǎn)介的詳細(xì)內(nèi)容。更多信息請(qǐng)關(guān)注PHP中文網(wǎng)其他相關(guān)文章！