The key to writing a good PHPDoc is to have clear structure and accurate information. First, we must follow the basic structural specifications, use /*/ package annotations, and use @param, @return, @throws and other tags reasonably; secondly, we must pay attention to the description details of parameters and return values, clearly explain the meaning and format, rather than just writing the type; then we can choose @var, @deprecated, @see, @link, @todo and other tags that enhance readability to improve document expression; finally, keep the description concise and not redundant, and use the array{} syntax of PHP 8.1 to explicitly return the structure, making PHPDoc more practical.

When writing PHPDoc, many people just add a comment, but it is not very useful. A truly useful PHPDoc is a structured comment that allows people to quickly understand the functions, parameters and return values, and can also be recognized by the IDE to improve code readability and maintenance.

The following points are the things you should pay attention to when writing PHPDoc.

Basic structure must be standardized

The basic format of PHPDoc is wrapped in /** */ , each line begins with an asterisk. The most common tags include:

• @param : Explain the type and meaning of each parameter
• @return : Explain the return value type and meaning
• @throws : If an exception is thrown, it must be noted

For example, this example:

 /**
 * Calculate the difference in the number of days between two dates*
 * @param string $startDate Start date, format Ymd
 * @param string $endDate End date, format Ymd
 * @return int Return the number of days difference* @throws Exception throws an exception if the date format is incorrect*/
function calculateDateDifference($startDate, $endDate) {
    // Function logic}

A few points to note:

• Parameter alignment looks good but not necessary. The key is accurate information
• Try to write specific types, such as string[] is clearer than array
• The description should be concise, without repeating the meaning of the variable name, but supplementing the purpose

Enhance readability with the right label

In addition to basic tags, some tags can make your documentation clearer:

• @var : used for variable annotation, especially array element types, etc.
• @deprecated : marking a function is deprecated, which alternative is recommended
• @see or @link : Quoting other methods or external documents
• @todo : Explain what may be improved in the future

For example:

 /**
 * Get basic information about users*
 * @deprecated Please use getUserProfile() instead of * @see getUserProfile()
 * @return array{ id: int, name: string } User information*/
function getUserInfo() {
    // ...
}

Although these tags are not necessary, they are very useful in teamwork or open source projects and can reduce communication costs.

Don't ignore the details of return values ??and parameters

Many PHPDoc comments only write parameter names and types, but do not specify the actual meaning. for example:

 @param string $format date format

It's better to write it as:

 @param string $format output format, supports 'Ymd' and 'd/m/Y'

In this way, when others call, they will know which formats you support, rather than guessing.

The same is true for the return value. If the returned array or object is returned, the structure can be described using array{} syntax supported by PHP 8.1:

 @return array{title: string, author: string, published: bool}

This way of writing is much better than array .

Basically that's it. PHPDoc does not need to be too complicated, but it needs to write down key information clearly, such as how to use parameters, what to return, and whether there are side effects. Writing well will not only make it easier for others to understand your code, but the IDE can also automatically complete and prompt errors. This is its real value.

The above is the detailed content of How to properly document a PHP function with PHPDoc?. For more information, please follow other related articles on the PHP Chinese website!