Question

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.

Answer 1

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 ?

• I generally consider that developpers don’t write comments often enough
• And generally forget to update them
• So, I try to make their life easier, and don’t duplicate comments
• Unless the comment in the child class has to be different from the one in the parent class.