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标记...结果是方法文档中方法到属性的超链接，以及超链接从属性到属性doc中的方法。可以认为它类似于 Clue 棋盘游戏中的“秘密通道”，将角落房间连接到对面的角落房间。

通过@uses标签可以满足的另一个意图是$ variables的文档将显示一个@usedby标签列表，显示影响属性的所有方法......当然，假设你已经尽职尽责关于将@uses标签放在这些方法中。

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;
  }
}

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

2 个答案: