PHP documentation, should I copy / paste if I extend the class?

Question

I have a PHP class with a method. In the base class (this is more like a prototype, but I don't use prototypes because we have to be backward compatible), I document the parameters and the description of the method.

Now I am expanding this class. In this new method (implementation), I have to re-document the parameters and description, should I leave it blank or leave only notes related to this particular implementation?

My goal is to have readable API documents created by PhpDoc and follow conventions.

Answer 1

Looking at a few examples in the Zend Framework, it seems that comments are mostly copied - and this sometimes leads to different comments.

The first example I will 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 look at a class that implements this interface, for example Zend_Http_Client_Adapter_Curl , you will 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 the parameters; and more information during 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 the child class, for example 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 to the parent class that has not been recreated in the child class.

Now what do I usually do?

• I generally think that developers do not write comments too often
• And generally forget to update them
• So, I try to make their life easier and not duplicate comments.
• If the comment in the child class should not differ from the comment in the parent class.

Answer 2

PhpDocumentor will show you whether the documented method is an override of the method in the parent class, and also if the method is overridden in the child class. Thus, in addition to all the information you added to the docblock method, you will also see that there is a parent method and / or a child method associated with the current method. This means that it’s useful for you to say something in the docblock method.

What I usually do is float the key generic language up in relation to the parent method, but I still have to say something about the child’s current method, as well as the grandson’s method. Whatever distinguishes the child method from the parent method and / or something other than this child method from other child methods that are its peers from the same parent, is the information that this docblock child method needs.

I will never copy / paste anything from parent to child ... I will instead clarify what the child is doing, who he is, in relation to his parent and / or his brothers and sisters. In addition, I try not to say anything about children inside the parent docblock, since the typical relationship between the parent and the child is performed as a way to ignore the need to know the specifics of the children.