Introduction to PhpDoc

Core points

• PhpDoc (PhpDocumentor) is a powerful tool that helps developers write code documents through special format annotations. It can generate documents in multiple formats, such as HTML, PDF, and CHM, which can be extracted through a web interface or command line interface.
• PhpDoc uses DocBlocks (multi-line C-style comments) to document code blocks. DocBlocks contains three optional parts: a short description, a detailed description, and a tag. The tag begins with the @ symbol, which specifies additional information about the code.
• The PhpDoc package is used to group relevant code elements in the generated document. You can specify packages for files and classes using the @package and @subpackage tags in the file-level or class-level DocBlock.
• PhpDoc can write documents for various code elements, including files, classes, functions and methods, class properties, global variables, include()/require() and define(). These elements can use certain common tags, but each has a specific tag.
• PhpDoc's command line tool is used to generate user-friendly documents based on PHP code that has been written. This tool offers a variety of document formats. For users who are not familiar with the command line interface, PhpDoc also provides a web interface.

Reading code written by others (who hasn't experienced it?) is a difficult task. The messy "pasta-style code" is mixed with a large number of weirdly named variables, making it dizzy. Does this function expect strings or arrays? Does this variable store integers or objects? After countless hours of code tracking and trying to understand the functionality of each part, it is common to give up and rewrite the entire code from scratch – it’s a waste of your precious time. PhpDoc (the short name for PhpDocumentor) is a powerful tool that allows you to easily write code documents with comments in special formats. Documents are not only available in source code, but also professional documents extracted through the web interface or command line interface. The result can be in a variety of formats such as HTML, PDF, and CHM. In addition, many IDEs that provide code completion can parse PhpDoc comments and provide practical features such as type prompts. By using PhpDoc, you can make it easier for others (and yourself) to understand your code—even after weeks, months, or even years after writing it. The easiest way to install PhpDoc is to use PEAR. Of course, PEAR must be installed before you do so. If you do not have PEAR installed, follow the instructions at pear.php.net/manual/en/installation.php. In this article, I will show you how to generate beautiful and user-friendly documents from beginning to end with PhpDoc.

DocBlocks

DocBlock is a multi-line C-style comment used to write documents for code blocks. It starts with /** and each line has an asterisk. Here is an example:

<?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 contains three parts: a short description, a detailed description, and a label. All three parts are optional. A short description is a concise description that ends with a newline or period. PhpDoc's analytical routine is smart; it ends with a short description only when the period is at the end of the sentence. A detailed description is the main content of a document; it can be multi-line and can be arbitrarily long. Both detailed descriptions and short descriptions can contain certain HTML elements for formatting. Unsupported HTML tags will be displayed as plain text. PhpDoc can generate documents in multiple formats, so HTML tags do not necessarily render as they do in HTML files; the actual format depends on the format of the generated document. If you need to display HTML tags as text, use double brackets. For example:

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

The tag section of

DocBlock contains any number of special tags represented by the @ symbol. Tags are used to specify additional information, such as expected parameters and their types. Most tags must be on their own rows, but some tags can be inlined. Inline tags are enclosed in curly braces and can appear in detailed descriptions and brief descriptions. For a complete list of tags, check out the relevant PhpDoc documentation. If you need a line to start with the @ symbol but don't want to interpret it as a label, you can escape it with a backslash. PhpDoc will automatically identify and parse the text list in the detailed description and the short description. However, it does not parse nested lists correctly. If you want to use nested lists, use HTML tags. Here is an example to illustrate what I mean:

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

*

项目 1

*

*

项目 1.1

*

项目 1.2

* *

项目 2

* */

(The following content will be briefly summarized due to space limitations and retained key information)

Bag

The PhpDoc package is used to group relevant code elements in the generated document. You can specify packages for files and classes that contain code written to inherit those packages. To specify a package, set the @package tag in the file-level or class-level DocBlock. (File-level and class-level DocBlocks will be discussed further in the next section). Package names can contain letters, numbers, dash, underscores, and square brackets ("[" and "]"). Here is an example of how to define a file package:

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

If you have multiple levels of packages and subpackages, you can use the @subpackage tag to define subpackages. Here is an example:

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

If the file or class does not specify a package, it will be set to the default package "default". You can specify other packages to use by default through the -dn command line option.

What documents can be written?

Not all code elements can be written using DocBlocks. Here is a list of code elements that can be written in the document:

• File
• Category
• Functions and methods
• Class attributes
• Global variables
• include()/require()
• define()

All of these elements can use certain common labels, but each element has a label specific to that element. I'll cover some elements and tags that are usually used to write documentation for them.

(The documentation examples of files, classes, functions and methods will be brief, only key tag descriptions will be retained)

Generate document

After writing the documentation for your PHP code, you need to generate user-friendly documents from it. To do this, run the PhpDoc command line tool.

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

(The command line parameter description will be brief)

For users who are not familiar with the command line interface, PhpDoc also provides a web interface. This document does not discuss it in detail, but you can learn more on PhpDoc's official website, phpdoc.org.

Summary

In this article, I introduce you to PhpDoc and its many powerful features. I've explained the purpose of DocBlocks and its components; I've shown you how to use packages to organize your documentation; I've explained which code elements can be written and some common examples; and finally, I've shown you how to generate documentation based on your source code. I highly recommend that you start using PhpDoc in your own project, even if it’s just writing the documentation for the most important parts. It's very simple and can save you and your colleagues countless hours of tension and pain.

(The FAQ section will be brief, retaining core questions and short answers)

The above is the detailed content of Introduction to PhpDoc. For more information, please follow other related articles on the PHP Chinese website!