Documenting PHP, should I copy/paste if I extend a class?

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.

Answer 2

PhpDocumentor is going to show you if the method being documented is a redefinition of the method in a parent class as well as if the method gets overridden in a child class. So, in addition to all info that you put in the method's docblock, you will also see that there is a parent method and/or child method associated to the current method. This means it is to your benefit to say something in the method's docblock.

What I tend to do is to float the key generic language upwards toward the parent method, but I'll still have something to say about the current child's method as well as a grandchild's method. Whatever differentiates the child method from the parent method, and/or whatever differentiates this child method from other child methods that are its peers from the same parent, is the info needed by this child method docblock.

I'm never going to copy/paste something from a parent to a child... I'm instead going to further clarify what makes the child who he is with regard to his parent and/or his siblings. Also, I try not to say anything about the children inside the parent's docblock, since the typical parent-child relationship is done as a way to abstract away needing to know the specifics of the children.