Documenter PHP, dois-je copier / coller si j'étendez une classe?

Question

J'ai une classe PHP avec une méthode. Dans la classe de base (il est plus comme un prototype, mais je ne suis pas en utilisant des prototypes parce que nous devons être rétrocompatible), je documente les paramètres et la description de la méthode.

Maintenant, je tends cette classe. Dans cette nouvelle méthode (la mise en œuvre) que je devrais re-documenter les paramètres et la description, dois-je laisser le champ vide, ou devrais-je laisser que des notes pertinentes applicables à cette mise en œuvre particulière?

Mon but est d'avoir docs API lisibles produites par phpdoc, et de suivre les conventions.

Answer 1

En regardant quelques exemples dans Zend Framework, il semble que les commentaires sont copiées-collées la plupart du temps -. Et cela conduit parfois à différents commentaires

Le premier exemple que je vais prendre est Zend_Http_Client_Adapter_Interface::connect, qui est déclaré comme suit:

/**
 * Connect to the remote server
 *
 * @param string  $host
 * @param int     $port
 * @param boolean $secure
 */
public function connect($host, $port = 80, $secure = false);

Et, si vous jetez un oeil à une classe qui implémente cette interface, comme Zend_Http_Client_Adapter_Curl, vous verrez:

/**
 * 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)

, copiez-coller des paramètres; et plus d'informations dans la mise en œuvre.

Un autre exemple serait Zend_Log_Writer_Abstract::_write:

/**
 * Write a message to the log.
 *
 * @param  array  $event  log data event
 * @return void
 */
abstract protected function _write($event);

Et, dans une classe d'enfants, comme Zend_Log_Writer_Db:

/**
 * Write a message to the log.
 *
 * @param  array  $event  event data
 * @return void
 */
protected function _write($event)

Ici encore, copier-coller; et une petite modification de la classe parente, qui n'a pas été recréés dans la classe enfant.

Maintenant, qu'est-ce que je fais en général?

• Je considère généralement que developpeurs ne pas écrire des commentaires assez souvent
• Et en général oublier pour les mettre à jour
• Alors, j'essaie de leur rendre la vie plus facile, et ne pas dupliquer les commentaires
• À moins que le commentaire dans la classe de l'enfant doit être différent de celui de la classe parente.

Answer 2

PhpDocumentor va vous montrer si la méthode étant documentée est une redéfinition de la méthode dans une classe parente ainsi que si la méthode est redéfinie dans une classe enfant. Ainsi, en plus de toutes les informations que vous mettez dans la docblock de la méthode, vous verrez aussi qu'il ya une méthode parent et / ou méthode d'enfant associée à la méthode actuelle. Cela signifie qu'il est à votre avantage pour dire quelque chose dans le docblock de la méthode.

Ce que je tends à faire est de laisser flotter le langage générique clé vers le haut vers la méthode mère, mais je vais encore avoir quelque chose à dire au sujet de la méthode de l'enfant en cours ainsi que la méthode d'un petit-enfant. Quelle que soit différencie la méthode des enfants à partir de la méthode mère, et / ou tout ce qui différencie cette méthode des enfants d'autres méthodes d'enfants qui sont ses pairs de la même mère, est l'information nécessaire par cette méthode d'enfant docblock.

Je ne vais jamais copier / coller quelque chose d'un parent à un enfant ... Je vais au lieu de préciser davantage ce qui rend l'enfant qui il est à l'égard de ses parents et / ou ses frères et sœurs. En outre, j'essaie pas de dire quoi que ce soit au sujet des enfants à l'intérieur du docblock du parent, puisque la relation typique parent-enfant est fait comme un moyen d'abstraire avoir besoin de connaître les spécificités des enfants.