Documentation guidelines for PHP functions

PHP function document specification requires that required fields include function name, parameters (including default parameters), return value and exception. Optional fields include description, alias, compatibility, deprecation, and removal version. Writing rules emphasize clear and concise language, use the DocBlock comment format, and practice cases to demonstrate function usage and type hints.

PHP function documentation writing specifications

To ensure writing clear and consistent function documentation, please follow the following specifications:

Required fields:

• Function name: The unique identifier of the function, expressed in CamelCase.
• Parameters: The list of parameters accepted by the function, named in sequence using $param1, $param2, etc.
• Default parameters: If the function's parameters have default values, please use = default_value after the parameter name to specify.
• Return value: The type of value returned by the function.
• Exceptions: List of exceptions that may be thrown by the function.
• Example: One or more code examples that demonstrate how the function is used.

Optional fields:

• Description: A brief description of the function's function and purpose.
• Alias: Any alias for the function.
• Compatibility: PHP versions supported by the function.
• Deprecated since PHP version: The deprecated version of the function.
• Removed since PHP version: The function has been removed from PHP version.

Writing Rules:

• Use clear and concise language.
• Avoid outdated terminology or jargon.
• Provide enough information so that developers understand how the function works.
• Use [DocBlock comment format](https://www.php.net/manual/en/language.types.declarations.php).

Practical case:

/**
 * 计算两个数的平均值。
 *
 * @param float $num1 第一个数
 * @param float $num2 第二个数
 * @return float 平均值
 */
function average(float $num1, float $num2): float
{
    return ($num1 + $num2) / 2;
}

Other tips:

• Use code snippets to demonstrate functions usage.
• Links to related functions or classes to provide more information.
• When possible, provide type hints to improve code readability.
• Regularly review documentation to ensure accuracy and consistency.

The above is the detailed content of Documentation guidelines for PHP functions. For more information, please follow other related articles on the PHP Chinese website!