4

我有一个带有方法的 PHP 类。在基类中（它更像一个原型，但我没有使用原型，因为我们必须向后兼容），我记录了方法的参数和描述。

现在我扩展了那个类。在这个新方法（实现）中，我应该重新记录参数和描述，我应该将其留空，还是应该只留下适用于该特定实现的相关注释？

我的目标是拥有由 PhpDoc 生成的可读 API 文档，并遵循约定。

4

2 回答 2

3

PhpDocumentor 将向您展示所记录的方法是否是对父类中方法的重新定义，以及该方法是否在子类中被覆盖。因此，除了您在方法的文档块中放入的所有信息之外，您还将看到与当前方法关联的父方法和/或子方法。这意味着在方法的文档块中说些什么对您有利。

我倾向于做的是将关键的通用语言向上浮动到父方法，但我仍然对当前子方法和孙方法有话要说。子方法与父方法的区别，和/或此子方法与其他子方法的区别，这些子方法与同一父方法对等，是此子方法文档块所需的信息。

我永远不会从父母那里复制/粘贴某些东西给孩子……相反，我将进一步阐明是什么让孩子成为了他的父母和/或兄弟姐妹。另外，我尽量不对父母文档块中的孩子说任何话，因为典型的父子关系是作为一种抽象方式来抽象出需要知道孩子的细节的。

于 2010-03-24T14:44:35.767 回答
1

查看 Zend Framework 中的几个示例，评论似乎大多是复制粘贴的——这有时会导致不同的评论。

我要举的第一个例子是Zend_Http_Client_Adapter_Interface::connect，它被声明为：

/**
 * Connect to the remote server
 *
 * @param string  $host
 * @param int     $port
 * @param boolean $secure
 */
public function connect($host, $port = 80, $secure = false);

而且，如果您看一下实现此接口的类，例如Zend_Http_Client_Adapter_Curl，您会看到：

/**
 * Initialize curl
 *
 * @param  string  $host
 * @param  int     $port
 * @param  boolean $secure
 * @return void
 * @throws Zend_Http_Client_Adapter_Exception if unable to connect
 */
public function connect($host, $port = 80, $secure = false)

所以，复制粘贴参数；以及实施中的更多信息。


另一个例子是Zend_Log_Writer_Abstract::_write：

/**
 * Write a message to the log.
 *
 * @param  array  $event  log data event
 * @return void
 */
abstract protected function _write($event);

并且，在子类中，例如Zend_Log_Writer_Db：

/**
 * Write a message to the log.
 *
 * @param  array  $event  event data
 * @return void
 */
protected function _write($event)

在这里，再次复制粘贴；以及父类中的一个小修改，尚未在子类中重新创建。


现在，我通常会做什么？

  • 我一般认为开发人员写评论的频率不够高
  • 而且通常忘记更新它们
  • 所以，我尽量让他们的生活更轻松，不要重复评论
  • 除非子类中的注释必须与父类中的注释不同。
于 2010-03-23T19:29:08.170 回答