phpdoc

phpdoc

If you’ve ever tried to read code written by someone other than yourself (who hasn’t?), you know it can be a daunting task. A jumble of “spaghetti code” mixed with numerous oddly named variables makes your head spin. Does this function expect a string or an array? Does this variable store an integer or an object? After countless hours of following the threads of code and trying to understand what each bit does, it’s not uncommon to give up and just rewrite the whole thing from scratch – a task that wastes far too much of your precious time.

如果您曾经尝试阅读由您自己以外的人(没有？)编写的代码，那么您知道这可能是一项艰巨的任务。 杂乱无章的“意大利面代码”与众多奇怪的变量混合在一起，会使您旋转。 此函数需要字符串还是数组？ 这个变量存储整数还是对象？ 经过无数小时的跟踪代码线程并尝试理解每个比特的作用之后，放弃并只是从头开始重写整个事情并不少见，这是一个浪费太多宝贵时间的任务。

PhpDoc, short for PhpDocumentor, is a powerful tool that allows you to easily document your code via specially formatted comments. The documentation will be available not only in the source code, but also in professional documentation extracted using either the web or command-line interface. The result can be in various formats such as HTML, PDF, and CHM. Additionally, many IDEs that provide code-completion can parse PhpDoc comments and provide useful features such as type-hinting. By using PhpDoc, you can make it easy for others (and yourself) to understand your code – weeks, months, and even years after you’ve written it.

PhpDoc是PhpDocumentor的缩写，是一个功能强大的工具，可让您通过特殊格式的注释轻松地编写代码。 该文档不仅在源代码中可用，而且在使用Web或命令行界面提取的专业文档中也可用。 结果可以采用各种格式，例如HTML，PDF和CHM。 此外，许多提供代码完成功能的IDE都可以解析PhpDoc注释并提供有用的功能，如类型提示。 通过使用PhpDoc，可以使他人(和您自己)在编写代码后数周，数月甚至数年内都易于理解您的代码。

The easiest way to install PhpDoc is with PEAR. Of course, before you can do so you must have PEAR installed. If you don’t, follow the instructions at pear.php.net/manual/en/installation.php.

安装PhpDoc的最简单方法是使用PEAR。 当然，必须先安装PEAR，然后才能这样做。 如果不这样做，请按照pear.php.net/manual/en/installation.php上的说明进行操作 。

In this article I’ll show you how to use PhpDoc to generate gorgeous and user-friendly documentation from beginning to end.

在本文中，我将向您展示如何使用PhpDoc从头到尾生成华丽且用户友好的文档。

文档块 (DocBlocks)

A DocBlock is a multi-line C-style comment used to document a block of code. It begins with /** and has an asterisk at the start of each line. Here’s an example:

DocBlock是多行C风格的注释，用于记录代码块。 它以/**开头，并且在每行的开头都有一个星号。 这是一个例子：

<?php /** * Calculates sum of squares of an array * * Loops over each element in the array, squares it, and adds it to * total. Returns total. * * This function can also be implemented using array_reduce(); * * @param array $arr * @return int * @throws Exception If element in array is not an integer */ 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 consist of three sections: short description, long description, and tags. All three sections are optional.

DocBlocks由三个部分组成：简短描述，详细描述和标签。 这三个部分都是可选的。

The short description is a succinct description terminated by either a new-line or a period. PhpDoc’s parsing routines are smart; it will only end the short description if the period is at the end of a sentence.

简短描述是用换行符或句号结尾的简洁描述。 PhpDoc的解析例程很聪明； 仅当句号在句子结尾时，它才会结束简短描述。

The long description is where the bulk of the documentation goes; it can be multi-line and as long you wish.

详细描述是大量文档的去向。 它可以是多行，只要您愿意。

Both the long and short descriptions may contain certain HTML elements for formatting. HTML tags that aren’t supported will be displayed as plain text. PhpDoc can generate the documentation in multiple formats, though, so the HTML tags aren’t necessarily rendered as they would in an HTML file; the actual formatting depends on the generated file format. If you need to display an HTML tag as text, use double brackets. For example:

长描述和短描述都可能包含某些用于格式化HTML元素。 不支持HTML标记将显示为纯文本。 不过，PhpDoc可以生成多种格式的文档，因此HTML标记不一定像在HTML文件中那样呈现。 实际的格式取决于生成的文件格式。 如果需要将HTML标签显示为文本，请使用双括号。 例如：

<?php /** * Here an example of the italics tag: <<i>>Hello, world!<<i>> */

The tags section of a DocBlock contains any number of special tags denoted by the @ symbol. The tags are used to specify additional information, such as the expected parameters and their type. Most tags must be on their own line, with the exception of certain tags which may be inline. Inline tags are surrounded with curly braces and may be in both the long and short description. For a full list of tags, check out the relevant PhpDoc documentation.

DocBlock的标签部分包含@符号表示的任意数量的特殊标签。 标签用于指定其他信息，例如预期的参数及其类型。 大多数标签必须位于自己的行上，但某些标签可能是内联的。 内联标签用花括号括起来，并且可能在长说明和短说明中都使用。 有关标签的完整列表，请查看相关的PhpDoc文档 。

If you need to start a line with the @ symbol but you don’t want it to be interpreted as a tag, you can escape it with a backslash.

如果您需要以@符号开头的行，但又不想将其解释为标签，则可以使用反斜杠对其进行转义。

PhpDoc will automatically recognize textual lists in the long and short descriptions and it will parse them. However, it won’t parse nested lists correctly. If you want to use nested lists, use the HTML tags. Here is an example to illustrate what I mean:

PhpDoc将自动识别长和短描述中的文本列表，并将对其进行解析。 但是，它不能正确解析嵌套列表。 如果要使用嵌套列表，请使用HTML标记。 这是一个例子来说明我的意思：

<?php /** * Example of using lists * * PhpDoc will parse this list correctly: * - Item #1 * - Item #2 * - Item #3 * * But not this list: * - Item 1 * - Item 1.1 * - Item 1.2 * - Item 2 * * Use this instead for a nested list: * <ul> * <li>Item 1</li> * <ul> * <li>Item 1.1</li> * <li>Item 1.2</li> * </ul> * <li>Item 2</li> * </ul> */

配套 (Packages)

PhpDoc packages are used to group related code elements in the generated documentation. You can specify packages for files and classes and the documented code they contain will inherit the package from them. To specify a package, set the @package tag in a file-level or class-level DocBlock (file-level and class-level DocBlocks will be discussed further is the following section). A package name may contain letters, numbers, dashes, underscores, and square brackets (“[” and “]”).

PhpDoc软件包用于将生成的文档中的相关代码元素分组。 您可以为文件和类指定程序包，它们所包含的文档化代码将继承它们。 要指定包，请在文件级或类级DocBlock中设置@package标记(以下部分将进一步讨论文件级和类级DocBlocks)。 包名称可以包含字母，数字，破折号，下划线和方括号(“ [”和“]”)。

Here is an example of defining a file’s package:

这是定义文件包的示例：

<?php /** * This is a file-level DocBlock * * @package Some_Package */

If you have multiple levels of packages and sub-packages, you can define a sub-package with the @subpackage tag. Here is an example:

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

<?php /** * This is a class-level DocBlock * * @package Some_Package * @subpackage Other */ class SomeClass { }

If a file or class doesn’t specify a package it will be set to the default package, “default”. You can specify a different package to be used by default when generating the documentation via the -dn command-line option.

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

我可以记录什么？ (What Can I Document?)

Not all code elements can be documented with DocBlocks. Here is a list of code elements that may be documented:

并非所有代码元素都可以用DocBlocks记录。 这是可能记录的代码元素的列表：

Files

档案 Classes

班级 Functions and methods

功能与方法 Class properties

类属性 Global variables

全局变量

include()/require()

include() / require()

define()

define()

All of these elements can use certain common tags, but each has tags that are specific to that element. I’ll go over a few of the elements and the tags normally used to document them.

所有这些元素都可以使用某些通用标签，但是每个元素都有特定于该元素的标签。 我将介绍一些通常用于记录它们的元素和标签。

档案 (Files)

File-level DocBlocks are used to document the contents of a file. It is highly recommended to include a file-level DocBlock in every file you document, and in fact PhpDoc will display a warning if one is not found when generating documentation.

文件级DocBlock用于记录文件的内容。 强烈建议您在文档中的每个文件中都包含一个文件级DocBlock，实际上，如果在生成文档时找不到该文件，PhpDoc将显示警告。

Most elements are documented by placing a DocBlock before the element, but files are an exception (since you can’t write anything before a file). File-level DocBlocks are placed on the first line of the file.

通过在元素之前放置DocBlock可以记录大多数元素，但是文件是一个例外(因为您不能在文件之前写任何东西)。 文件级DocBlocks放置在文件的第一行。

A file-level DocBlock usually contains the tags @package, @subpackage, @license, and @author. The @package and @subpackage tags were discussed earlier. The @license tag is used to specify a URL to an external license that covers your code. The tag must contain the URL to the license and optionally a title. The @author tag is used to specify the author of the file. It must contain the author’s name and optionally an email address in angle brackets.

文件级的文档块通常包含标签@package ， @subpackage ， @license和@author 。 @package和@subpackage标记已在前面讨论过。 @license标记用于指定包含您的代码的外部许可证的URL。 标签必须包含许可证的URL和标题(可选)。 @author标记用于指定文件的作者。 它必须在尖括号中包含作者的姓名和(可选)电子邮件地址。

Unlike most elements, a file-level DocBlock must contain a @package tag in order to be parsed properly.

与大多数元素不同，文件级DocBlock必须包含@package标记才能正确解析。

Here is a complete example of a file-level DocBlock:

这是文件级DocBlock的完整示例：

<?php /** * This file contains common functions used throughout the application. * * @package MyProject * @subpackage Common * @license http://opensource.org/licenses/gpl-license.php GNU Public License * @author Moshe Teutsch <moteutsch@gmail.com> */

班级 (Classes)

A class-level DocBlock is placed before a class definition and should describe the meaning of the class. Like file-level DocBlocks, class-level DocBlocks usually contain the tags @package, @subpackage, and @author. Here is an example:

类级别的DocBlock放置在类定义之前，并应描述类的含义。 像文件级文档块，类级别的文档块通常包含标签@package ， @subpackage和@author 。 这是一个例子：

<?php /** * An example class * * The class is empty for the sake of this example. * * @package MyProject * @subpackage Common * @author Moshe Teutsch <moteutsch@gmail.com> */ class Example { }

功能与方法 (Functions and methods)

Functions and methods are documented identically in PhpDoc. (For those who may not be familiar with the terminology, a method is just a function within a class.) Functions and methods usually contain the @param and @return tags in their DocBlocks. The @param tag is used to document the expected type of a parameter. It contains three sections: the parameter, the data type, and an optional description. The @return tag is used to document the return type. It contains two sections: the data type and an optional description. In both tags, the data type can be either a valid PHP data type, a class name, or “mixed”. It can also contain multiple options separated by a pipe.

函数和方法在PhpDoc中有相同的记录。 (对于可能不熟悉术语的人，方法只是类中的一个函数。)函数和方法通常在其DocBlocks中包含@param和@return标记。 @param标记用于记录参数的预期类型。 它包含三个部分：参数，数据类型和可选描述。 @return标记用于记录返回类型。 它包含两部分：数据类型和可选描述。 在这两个标记中，数据类型可以是有效PHP数据类型，类名或“混合”。 它还可以包含由管道分隔的多个选项。

<?php /** * Finds and returns user by ID or username * * @param int|string $user Either an ID or a username * @param PDO $pdo A valid PDO object * @return User Returns User object or null if not found */ function getUser($user, PDO $pdo) { // ... if ($isFound) { return new User(...); } return null; }

产生文件 (Generating Documentation)

Once you’ve documented your PHP code, you’ll want to generate user-friendly documentation from it. To do so, run the PhpDoc command-line tool.

在记录了您PHP代码之后，您将希望从中生成用户友好的文档。 为此，请运行PhpDoc命令行工具。

moteutsch@vivaldi:~$ phpdoc -d /path/to/files/ -t /path/to/docs/ -ti 'Documentation Title' -dn 'Default Package' -o HTML:frames:default

The -d option specifies a comma-separated list of directories containing files to document, and -t the path to generated docs. -ti is used to specify the project title, and -dn to set the default package name. Finally, -o specifies the documentation format. PhpDoc has a wide selection of formats to choose from. A full list is available on the PhpDoc website.

-d选项指定以逗号分隔的目录列表，其中包含要记录的文件，而-t是生成文档的路径。 -ti用于指定项目标题， -dn用于设置默认程序包名称。 最后， -o指定文档格式。 PhpDoc有多种格式可供选择。 完整的列表可在PhpDoc网站上找到 。

You can find out more about the command-line tool by executing the help command as follows:

您可以通过执行如下的help命令来找到有关命令行工具的更多信息：

moteutsch@vivaldi:~$ phpdoc -h

Once you run the command, the documentation path you specified should contain the generated docs.

运行命令后，您指定的文档路径应包含生成的文档。

For those of you who aren’t comfortable using the command-line interface, PhpDoc also has a web interface available. It’s outside of this articles scope to discuss it at length, but you can read more about it on PhpDoc’s official website, phpdoc.org.

对于那些不习惯使用命令行界面的人，PhpDoc还提供了一个Web界面。 对其进行详细讨论不在本文讨论范围之内，但是您可以在PhpDoc的官方网站phpdoc.org上阅读有关它的更多信息。

摘要 (Summary)

In this article I’ve given you a first look at PhpDoc and its many powerful features. I have explained the purpose of DocBlocks and their components; I have shown you how to organize your documentation using packages; I have explained which code elements can be documented and some common examples of doing so; finally, I have shown you how to generate documentation from your source code. I highly recommend that you start using PhpDoc in your own projects, if even only to document the most important parts. It is very straight-forward and will save you and your co-workers countless hours of nail-biting and hair-pulling.

在本文中，我首先向您介绍了PhpDoc及其许多强大的功能。 我已经解释了DocBlocks及其组件的用途。 我已经向您展示了如何使用软件包来组织文档。 我已经解释了可以记录哪些代码元素以及这样做的一些常见示例。 最后，我向您展示了如何从源代码生成文档。 我强烈建议您开始在自己的项目中使用PhpDoc，即使只是为了记录最重要的部分。 这非常简单，可以为您和您的同事节省数小时的咬指甲和拔头发的时间。

Image via Zadorozhnyi Viktor / Shutterstock

图片来自Zadorozhnyi Viktor / Shutterstock

翻译自: https://www.sitepoint.com/introduction-to-phpdoc/

phpdoc

相关资源：使用phpdoc/phpDocumentor来生成api文档