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)
  {
    // ...
  }

  Copy after login

@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
  {
    // ...
  }

  Copy after login

@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
  {
    // ...
  }

  Copy after login

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
{
    // ...
}

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

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