php - 如何用 phpdoc 记录修改受保护属性的方法？

Question

用 phpdoc 记录修改受保护属性的方法的最佳方法是什么？

例如，记录下面的 setVar() 方法的正确方法是什么？

class Test {
  protected $variables = array();

  public function setVar($name, $value) {
    $this->$variables[$name] = $value;
  }
}

提前致谢，

.L.

Answer 1

我想这取决于您为什么要强调该方法会影响该受保护的属性...

如果您只想“说”它，只需在描述中说出来，无论是否使用内联 @link 标签：

/**
 * Setter for $variables or {@link Test::$variables}
 * ...

通过使用内联@link，在方法的描述中生成指向 $variables 文档的超链接。

您可以使用 @see 标记作为对该属性的独立引用：

/**
 * Setter
 * @see Test::$variables 
 * ...

这也为属性的文档创建了一个超链接，但它通过拥有自己的标签更加突出。

如果要创建从方法到属性的“指针”，请使用 @uses 标记：

/**
 * Setter
 * @uses Test::$variables
 * ...

这里方法中的@uses 标记会自动在$variables 属性的文档中放置一个@usedby 标记...结果是从方法到方法文档中的属性的超链接，以及来自属性的超链接属性文档中的方法。可以把它想象成类似于线索棋盘游戏中的“秘密通道”，将角落房间连接到对面的角落房间。

通过@uses 标签可以满足的另一个目的是$variables 的文档将显示@usedby 标签的列表，这些标签显示影响属性的所有方法......当然，假设您一直认真地把@在这些方法中使用标签。

Answer 2

我通常使用类似于以下的东西，尽管可能有更好的方法。

class Test {
  protected $variables = array();

 //**
   * Setter for $this->variables
   *
   * @var string
   * @var string
   * @returns void
   */
  public function setVar($name, $value) {
    $this->$variables[$name] = $value;
  }
}