在 PHP 开发中，为了保持代码的可读性和可维护性，编写有效的文档注释是至关重要的。PHPDoc 是一种为 PHP 代码添加注释的标准，通过使用特定的标签，开发者可以对代码的各个部分进行详细的说明。本文将详细介绍最常见的 PHPDoc 标签，并解释它们的用途。

什么是 PHPDoc？

PHPDoc 是用于为 PHP 源代码提供结构化注释的模型。这些注释帮助开发者理解类、方法、函数、属性等的目的和使用方式，提供良好文档支持的程序代码可以更容易被理解、维护和扩展。

PHPDoc 标签详解

参数与返回值说明

• @param: 描述函数或方法的参数。

  /**
   * @param int $age The age of the person.
   */
  

• @return: 描述函数或方法的返回值。

  /**
   * @return bool True if successful, false otherwise.
   */
  

类型与属性说明

• @var: 描述变量或属性的类型。

  /**
   * @var string The name of the person.
   */
  

• @property: 描述类的动态属性。

  /**
   * @property string $name The name of the person.
   */
  

• @property-read: 描述类的只读属性。

  /**
   * @property-read int $id This ID is read-only.
   */
  

• @property-write: 描述类的只写属性。

  /**
   * @property-write string $name You can only set the name.
   */
  

异常与用法

• @throws: 指出函数可能抛出的异常。

  /**
   * @throws \InvalidArgumentException If the argument is invalid.
   */
  

• @uses: 说明代码中使用的其他类或方法。

  /**
   * @uses SomeClass::someMethod()
   */
  

元信息

• @author: 记录代码作者信息。

  /**
   * @author John Doe <john.doe@example.com>
   */
  

• @version: 声明代码版本信息。

  /**
   * @version 1.0.0 Initial release.
   */
  

• @deprecated: 指出不推荐使用的代码。

  /**
   * @deprecated 1.2.0 Use newFunction() instead.
   */
  

• @since: 记录功能加入的版本。

  /**
   * @since 1.0.0 This method is available.
   */
  

• @license: 描述代码使用的许可证信息。

  /**
   * @license MIT
   */
  

其他有用标签

• @todo: 标记需要完成的任务或改进的地方。

  /**
   * @todo Refactor this method to improve performance.
   */
  

• @link: 提供超链接到相关资源。

  /**
   * @link http://example.com More information.
   */
  

• @see: 提供文档中相关部分的参考信息。

  /**
   * @see http://example.com
   */
  

• @requires: 指明执行当前代码所需的条件。

  /**
   * @requires PHP 7.4 This feature requires PHP 7.4.
   */
  

• @method: 描述类中使用的动态方法。

  /**
   * @method void doSomething(int $times) Do something multiple times.
   */
  

结论

利用 PHPDoc 对代码进行注释，不仅可以帮助自己更好地理解代码逻辑，也能让团队中的其他开发者在阅读和维护代码时更高效。通过上述列举出的标签，您可以为 PHP 项目提供完整的、结构化的文档支持。