Comment utiliser phpdoc dans Eclipse

Question

Nous sommes actuellement au début d'un nouveau projet, et que vous souhaitez (pour une fois) commentaire le plus possible dès le début pour aider le développement futur.

J'ai essayé de savoir quelles sont les meilleures pratiques de l'utilisation phpDoc dans Eclipse, mais avec des résultats assez minces.

Pouvez-vous partager vos meilleures pratiques et astuces d'utilisation phpDoc pour commenter des choses dans Eclipse?

Answer 1

Il n'y a pas « standard réel » sur ce qui devrait être commenté et comment, mais certaines balises sont utilisées par presque tout le monde qui commente son code.

Par exemple, j'utilise généralement au moins:

• une brève description
• optionnellement, une longue description
• @param type name description: pour les paramètres des fonctions / méthodes
• @returns type: pour la valeur de retour des fonctions / méthodes
• @throws ExceptionType: si les fonctions / méthodes renvoie une exception dans certaines circonstances
• @see ... : Quand je veux faire une référence à un autre fichier ou une URL qui donne plus d'informations
• en fonction de la structure du projet, je peux aussi utiliser @package et @subpackage
• Une autre qui est agréable quand vous avez des propriétés magiques dans une classe (ils ne peuvent pas être vus par votre IDE, comme ils sont écrits dans le code) est @property type $name: il permet Eclipse PDT faire automatique l'achèvement, même sur les propriétés magiques -. Doctrine utilise, par exemple

La plupart d'entre eux sont utilisés par Eclipse PDT pour vous aider lors du codage (en particulier @param) ; mais ne hésitez pas à ajouter d'autres qui ne sont pas utilisés par Eclipse PDT: si vous créez la documentation de votre code, il peut toujours être utile; -)

Le meilleur conseil que je peux vous donner serait de jeter un oeil à la source de code de quelques grandes applications et / ou des cadres (Zend Framework, Doctrine, ...) , pour voir comment leur code est a commenté - il est probable qu'ils utilisent quelque chose qui est bien accepté

.

Par exemple, si vous jetez un oeil à un code Zend Framework, vous pouvez trouver des trucs comme ça pour une classe:

/**
 * @package    Zend_Cache
 * @subpackage Zend_Cache_Backend
 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */
class Zend_Cache_Backend_Apc extends Zend_Cache_Backend implements Zend_Cache_Backend_ExtendedInterface

Et comme celui-ci pour une méthode:

/**
 * Test if a cache is available for the given id and (if yes) return it (false else)
 *
 * WARNING $doNotTestCacheValidity=true is unsupported by the Apc backend
 *
 * @param  string  $id                     cache id
 * @param  boolean $doNotTestCacheValidity if set to true, the cache validity won't be tested
 * @return string cached datas (or false)
 */
public function load($id, $doNotTestCacheValidity = false)

Quoi qu'il en soit, la chose la plus importante est d'être cohérent: tous les membres de votre équipe commente la même manière, suivez les mêmes conventions

.

Answer 2

Au strict minimum, je au moins coller avec ce que les étiquettes phpdoc minimal sont insérés automatiquement par Eclipse en fonction de votre code.

Le deuxième niveau minimal je serait pour efforcerai de garder lui-même PhpDocumentor heureux. Une fois que vous exécutez PhpDocumentor contre votre code, recherchez la page errors.html à la racine de vos documents. Ceci listera quoi que ce soit PhpDocumentor n'aime pas, comme ne pas avoir docblocks niveau de fichier. Vous pouvez chercher à mettre cette liste d'erreurs à zéro.

Le troisième niveau, vous pouvez chercher à atteindre serait de satisfaire l'une des normes de codage incluses dans l'application PHP_CodeSniffer à PEAR [1]. Un inconvénient ici est que ces normes plus concentrer spécifiquement sur les code lui-même, mais toutes les normes font des règles relatives à la documentation du code.

[1] - http://pear.php.net/package/PHP_CodeSniffer