記錄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中的孩子的任何事情，因爲典型的親子關係是通過抽象的方式來了解孩子的具體情況。