PHPDOC简介

核心要点

• PhpDoc (PhpDocumentor) 是一款强大的工具，通过特殊格式的注释帮助开发者编写代码文档。它能生成多种格式的文档，例如 HTML、PDF 和 CHM，可以通过 Web 界面或命令行接口提取。
• PhpDoc 使用 DocBlocks（多行 C 风格注释）来为代码块编写文档。DocBlocks 包含三个可选部分：简短描述、详细描述和标签。标签以 @ 符号开头，用于指定有关代码的附加信息。
• PhpDoc 包用于在生成的文档中对相关的代码元素进行分组。可以使用文件级或类级的 DocBlock 中的 @package 和 @subpackage 标签为文件和类指定包。
• PhpDoc 可以为各种代码元素编写文档，包括文件、类、函数和方法、类属性、全局变量、include()/require() 和 define()。这些元素可以使用某些通用标签，但也各自拥有特定标签。
• PhpDoc 的命令行工具用于根据已编写文档的 PHP 代码生成用户友好的文档。该工具提供多种文档格式。对于不熟悉命令行界面的用户，PhpDoc 还提供 Web 界面。

阅读他人编写的代码（谁没经历过？）是一项艰巨的任务。杂乱的“意大利面条式代码”与大量奇怪命名的变量混杂在一起，令人头晕目眩。这个函数期望的是字符串还是数组？这个变量存储的是整数还是对象？经过无数小时的代码追踪和试图理解每个部分的功能后，放弃并从头重写整个代码是很常见的——这浪费了您宝贵的时间。PhpDoc（PhpDocumentor 的简称）是一个强大的工具，允许您通过特殊格式的注释轻松编写代码文档。文档不仅可在源代码中获得，还可通过 Web 界面或命令行接口提取的专业文档中获得。结果可以是多种格式，例如 HTML、PDF 和 CHM。此外，许多提供代码完成功能的 IDE 可以解析 PhpDoc 注释并提供类型提示等实用功能。通过使用 PhpDoc，您可以使其他人（以及您自己）更容易理解您的代码——即使是在编写代码几周、几个月甚至几年之后。最简单的 PhpDoc 安装方法是使用 PEAR。当然，在您这样做之前，必须安装 PEAR。如果您没有安装 PEAR，请按照 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 包含三个部分：简短描述、详细描述和标签。所有三个部分都是可选的。简短描述是一个简洁的描述，以换行符或句点结尾。PhpDoc 的解析例程很智能；只有当句点位于句尾时，它才会结束简短描述。详细描述是文档的主要内容；它可以是多行的，并且可以任意长。详细描述和简短描述都可以包含某些 HTML 元素以进行格式化。不支持的 HTML 标签将显示为纯文本。PhpDoc 可以生成多种格式的文档，因此 HTML 标签不一定像在 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

* */

(以下内容因篇幅限制，将简略概括，保留关键信息)

包

PhpDoc 包用于在生成的文档中对相关的代码元素进行分组。您可以为文件和类指定包，它们包含的已编写文档的代码将继承这些包。要指定包，请在文件级或类级 DocBlock 中设置 @package 标签。（文件级和类级 DocBlocks 将在下一节中进一步讨论）。包名称可以包含字母、数字、短划线、下划线和方括号（“[”和“]”）。以下是如何定义文件包的示例：

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

如果您有多个级别的包和子包，则可以使用 @subpackage 标签定义子包。这是一个示例：

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

如果文件或类未指定包，则它将设置为默认包“default”。您可以通过 -dn 命令行选项指定要默认使用的其他包。

可以编写哪些文档？

并非所有代码元素都可以使用 DocBlocks 编写文档。以下是可以编写文档的代码元素列表：

• 文件
• 类
• 函数和方法
• 类属性
• 全局变量
• 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 还提供 Web 界面。本文档不详细讨论它，但您可以在 PhpDoc 的官方网站 phpdoc.org 上了解更多信息。

总结

在本文中，我向您介绍了 PhpDoc 及其许多强大的功能。我已经解释了 DocBlocks 的用途及其组成部分；我已经向您展示了如何使用包来组织您的文档；我已经解释了哪些代码元素可以编写文档以及一些常见的示例；最后，我已经向您展示了如何根据您的源代码生成文档。我强烈建议您在自己的项目中开始使用 PhpDoc，即使只是编写最重要的部分的文档。它非常简单，可以为您和您的同事节省无数小时的紧张和痛苦。

(FAQ 部分将被简略，保留核心问题和简短答案)

以上是PHPDOC简介的详细内容。更多信息请关注PHP中文网其他相关文章！