PHPDoc : Différence entre versions

Version du 26 mai 2009 à 13:38

Commenter un code est la meilleure aide que vous pouvez donner aux développeurs qui réutiliseront votre code.

Pour cela, nous conseillons d'utiliser la syntaxe de PHPDoc pour vos commentaires. PHPDoc est une adaptation de JavaDoc au langage PHP. Un commentaire écrit en PHPDoc sera facilement compréhensible par un développeur ainsi que par des logiciels générateurs de documentations (PHPDocumentor, Doxygen, PHPDoc, AutoPHPDoc...). Des éditeurs de codes savent interpréter le PHPDoc pour faire de l'auto-suggestion (ex : Eclipse).

Exemples de commentaires

Commentaire sur une propriété de classe : <source lang="php">

   /**
    * Message de bienvenue
    *
    * @var    string message de bienvenue
    * @access private
    */
   var $message;

</source>

Commentaire sur une méthode de classe : <source lang="php">

   /**
    * Créé le message
    * et le stocke dans $this->message
    *
    * @access  public
    * @return  none
    */
   function creationMessage() {
      
   }

</source>

Syntaxes

On utilise la balise de commentaires pour lignes multiples : <source lang="php"> /* */ </source>

Les premières lignes sont dédiées à la description de l'objet commenté.

Pour préciser la version d'une fonction, l'auteur d'une classe ou encore le type de l'objet, .