I have a PHP class with a method. In the base class (it's more like a prototype, but I'm not using prototypes because we have to be backwards compatible), I document the parameters and description of the method.
Now I extend that class. In this new method (the implementation) should I re-document the parameters and description, should I leave it blank, or should I only leave relevant notes that apply to that particular implementation?
My goal is to have readable API docs produced by PhpDoc, and to follow conventions.
Looking at a couple of examples in Zend Framework, it seems the comments are mostly copy-pasted -- and this sometimes leads to different comments.
The first example I'll take is Zend_Http_Client_Adapter_Interface::connect, which is declared as :
/**
* Connect to the remote server
*
* @param string $host
* @param int $port
* @param boolean $secure
*/
public function connect($host, $port = 80, $secure = false);
And, if you take a look at a class that implements this interface, like Zend_Http_Client_Adapter_Curl, you'll see :
/**
* 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)
So, copy-paste of the parameters ; and more informations in the implementation.
Another example would be Zend_Log_Writer_Abstract::_write :
/**
* Write a message to the log.
*
* @param array $event log data event
* @return void
*/
abstract protected function _write($event);
And, in a child class, like Zend_Log_Writer_Db :
/**
* Write a message to the log.
*
* @param array $event event data
* @return void
*/
protected function _write($event)
Here, again, copy-paste ; and a small modification in the parent class, that has not been re-created in the child class.
Now, what do I generally do ?