记录 PHP，如果我扩展一个类，我应该复制/粘贴吗？

Question

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

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

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

Answer 1

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

我倾向于做的是将关键通用语言向上浮动到父方法，但我仍然对当前子方法以及孙方法有话要说。无论子方法与父方法有何不同，和/或该子方法与来自同一父方法的其他子方法的不同之处，都是该子方法文档块所需的信息。

我永远不会将父母的某些东西复制/粘贴到孩子身上......相反，我将进一步澄清是什么让孩子成为他的父母和/或他的兄弟姐妹。另外，我尝试不谈论父文档块内的子元素，因为典型的父子关系是作为一种抽象方式来消除需要了解子元素的具体情况的。

Answer 2

查看 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)

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

现在，我一般做什么？

• 我通常认为开发人员写注释的频率不够高
• 并且通常忘记更新它们
• 所以，我试图让他们的生活更轻松，并且不要重复注释
• 除非子类中的注释必须与父类中的不同。