Does the PHP function documentation writing specification change with changes in PHP versions?

PHP function documentation writing specifications continue to evolve with PHP version updates. The main changes include: PHP 5.x version uses documentation blocks in JavaDoc format. PHP 7.x version introduces PHPDoc annotation syntax to support type declaration and exception handling documents. PHP 8.x releases introduced version tags, return value type unions, and booster type declarations.

Version evolution of PHP function documentation specifications

Changes in PHP function documentation specifications are closely related to updates to PHP versions. Over time, the PHP team continues to optimize and improve documentation writing rules to improve document readability, consistency, and accuracy.

PHP 5.x version

• Document block format: Similar to JavaDoc, use /**...*/ as a document block.
• Tags: Use tags starting with @ to indicate function information, such as @param, @return, etc.
• Description: Describe the purpose and usage of the function clearly and concisely.
• Examples: It is recommended to use code examples to show the usage of functions.

PHP 7.x version

• Introduction of PHPDoc: Adopts PHPDoc annotation syntax and extends the document specification.
• Type declaration: Add a type declaration to clarify the function parameters and return value types.
• Exception handling documentation: Add the @throws tag of the documentation block to mark exceptions that may be thrown by the function.
• Visibility tag: Introducing the @access tag to identify the visibility of the function (public, protected, private).

PHP 8.x version

• Version tag: Add @psalm-version in front of the documentation block tag, specifying which PHP version the document applies to.
• Return value type union: Allows the use of type union to declare the return value type, indicating that the function can return multiple types.
• Propeller type: You can use the yield type declaration to return the propeller.

Practical case

The following is the max() function documentation block written in accordance with the latest PHP 8.x specifications:

/**
 * @psalm-version 8.0
 * @param array<scalar> $values Array of scalar values
 * @return scalar The maximum value in the array
 * @throws TypeError if any value in the array is not scalar
 */
function max(array $values): scalar
{
    if (!empty($values)) {
        $max = $values[0];
        foreach ($values as $value) {
            if ($value > $max) {
                $max = $value;
            }
        }
        return $max;
    }
    throw new TypeError('Array must contain at least one scalar value');
}

This documentation block follows the latest specifications and includes version labels, parameter type declarations, return value type unions, exception handling documentation and descriptions.

The above is the detailed content of Does the PHP function documentation writing specification change with changes in PHP versions?. For more information, please follow other related articles on the PHP Chinese website!