How to write standard PHP function documentation?

Writing documentation for PHP functions should follow standardized conventions, including naming conventions, specifying parameter types, return value types, and exception types using the @param, @return, and @throws tags, and adopting the PSR-5 comment block standard. The following is an example of a compliant comment block: /**Login user @param string $name Username @param string $password Password @return bool Whether the login is successful @throws InvalidArgumentException If $name or $password is empty*/function login(string $name, string $password): bool{// ...}

How to write standardized PHP function documentation

Introduction

Writing clear and comprehensive documentation for PHP functions is essential for modularity and maintainability Code collaboration with the team is critical. Following standardized documentation conventions helps ensure documentation is consistent and easy to understand.

Naming convention

• Function names should start with a lowercase letter and use underscores to separate words (for example: my_function).
• Follow the PSR-2 naming convention and use camel case naming for classes and methods (for example: MyFunction).

@param tag

• Use the @param tag to specify the type and description of the function parameters.

• For example:

  /**
   * @param string $name 用户名
   * @param string $password 密码
   */
  function login(string $name, string $password)
  {
    // ...
  }

@return tag

• Use @return## The # tag specifies the return value type and description of the function.
• For example:

  /**
   * @return bool 登录是否成功
   */
  function login(string $name, string $password): bool
  {
    // ...
  }

@throws tag

Use
• @throws## The # tag specifies the type and description of exceptions that may be thrown by the function.
For example:

• /**
   * @throws InvalidArgumentException 如果 $name 或 $password 为空
   */
  function login(string $name, string $password): bool
  {
    // ...
  }

Example of comment block

Example of function comment conforming to PSR-5 comment block standard ：

/**
 * 登陆用户
 *
 * @param string $name 用户名
 * @param string $password 密码
 * @return bool 登录是否成功
 * @throws InvalidArgumentException 如果 $name 或 $password 为空
 */
function login(string $name, string $password): bool
{
    // ...
}

Practical case

No parameter function

/**
 * 获取当前时间
 *
 * @return string 当前时间字符串
 */
function get_current_time(): string
{
    return date('Y-m-d H:i:s');
}

Multiple parameter function

/**
 * 计算两个数字的和
 *
 * @param int $a 第一个数字
 * @param int $b 第二个数字
 * @return int 和
 */
function sum(int $a, int $b): int
{
    return $a + $b;
}

Don’t forget

to use standardized conventions.

• Write clear and concise descriptions.
• Covers all possible situations.
• Documentation is updated regularly to reflect code changes.

The above is the detailed content of How to write standard PHP function documentation?. For more information, please follow other related articles on the PHP Chinese website!