用 phpdoc 记录修改受保护属性的方法的最佳方法是什么?
例如,记录下面的 setVar() 方法的正确方法是什么?
class Test {
protected $variables = array();
public function setVar($name, $value) {
$this->$variables[$name] = $value;
}
}
提前致谢,
.L.
我想这取决于您为什么要强调该方法会影响该受保护的属性...
如果您只想“说”它,只需在描述中说出来,无论是否使用内联 @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 标签的列表,这些标签显示影响属性的所有方法......当然,假设您一直认真地把@在这些方法中使用标签。
我通常使用类似于以下的东西,尽管可能有更好的方法。
class Test {
protected $variables = array();
//**
* Setter for $this->variables
*
* @var string
* @var string
* @returns void
*/
public function setVar($name, $value) {
$this->$variables[$name] = $value;
}
}