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

Question

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

现在我扩展这个类。在这种新方法（实施）中，我是否应该重新记录参数和说明，是否应该留空，还是只留下适用于特定实施的相关说明？

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

Answer 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) 

因此，复制粘贴的参数;以及更多的实施信息。

另一个例子是​​：

/** 
* 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) 

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

现在，我通常会做什么？

• 我一般认为developpers不写评论往往不够
• 而且一般忘记这么更新它们
• ，我尽量让自己的生活更轻松，并且不要重复评论
• 除非子类中的注释必须与父类中的注释不同。

Answer 2

PhpDocumentor会告诉你，如果记录的方法是在父类中重新定义该方法以及方法在子类中被覆盖。因此，除了您在方法的docblock中放入的所有信息外，您还将看到与当前方法关联的父方法和/或子方法。这意味着您在方法的docblock中说对您有益。

我倾向于将关键泛型语言向上抛向父方法，但对于当前孩子的方法以及孙子的方法，我仍然有些话要说。无论将子方法与父方法区分开来，还是/或将此子方法与来自同一父级的其他子方法区分开来，都是此子方法docblock所需的信息。

我永远不会从父母那里复制/粘贴一些东西给孩子......我反而会进一步澄清是什么让孩子与他的父母和/或他的兄弟姐妹有关。此外，我尝试而不是来说明父母的docblock中的孩子的任何事情，因为典型的亲子关系是通过抽象的方式来了解孩子的具体情况。