PHPDoc : Différence entre versions
(→Syntaxes) |
|||
| (4 révisions intermédiaires par 2 utilisateurs non affichées) | |||
| Ligne 7 : | Ligne 7 : | ||
Commentaire sur une propriété de classe : | Commentaire sur une propriété de classe : | ||
<source lang="php"> | <source lang="php"> | ||
| − | + | ||
| − | + | /** | |
| − | + | * Message de bienvenue | |
| − | + | * | |
| − | + | * @var string message de bienvenue | |
| − | + | * @access private | |
| − | + | */ | |
| + | var $message; | ||
| + | |||
</source> | </source> | ||
Commentaire sur une méthode de classe : | Commentaire sur une méthode de classe : | ||
<source lang="php"> | <source lang="php"> | ||
| − | + | /** | |
| − | + | * Créé le message | |
| − | + | * et le stocke dans $this->message | |
| − | + | * | |
| − | + | * @access public | |
| − | + | * @return none | |
| − | + | */ | |
| − | + | function creationMessage() { | |
| − | + | } | |
</source> | </source> | ||
==Syntaxes== | ==Syntaxes== | ||
| − | On utilise la balise de commentaires pour lignes multiples : | + | On utilise la balise de commentaires pour lignes multiples (les 2 étoiles en première ligne sont nécessaires à l'interprétation des commentaires comme étant du PHPDoc) : |
<source lang="php"> | <source lang="php"> | ||
| − | /* */ | + | /** |
| + | * | ||
| + | * | ||
| + | */ | ||
</source> | </source> | ||
| Ligne 41 : | Ligne 46 : | ||
Pour préciser la version d'une fonction, l'auteur d'une classe ou encore le type de l'objet, on utilise des tags préfixés par le caractère arobas @ : | Pour préciser la version d'une fonction, l'auteur d'une classe ou encore le type de l'objet, on utilise des tags préfixés par le caractère arobas @ : | ||
| − | {| class=" | + | {| class="prettytable sortable" |
|+ Tags PHPDoc | |+ Tags PHPDoc | ||
! Tag | ! Tag | ||
| Ligne 72 : | Ligne 77 : | ||
|- | |- | ||
|@global | |@global | ||
| − | |type (string, int, boolean, array, object NomObjet...) $globalvarname | + | |type(string, int, boolean, array, object NomObjet...) $globalvarname |
|Variable globale. | |Variable globale. | ||
|- | |- | ||
| Ligne 84 : | Ligne 89 : | ||
|- | |- | ||
|@param | |@param | ||
| − | |type [$varname] description | + | |type(string, int, boolean, array, object NomObjet...) [$varname] description |
| − | | | + | |Décrit un paramètre à une fonction |
|- | |- | ||
|@return | |@return | ||
| − | |type description | + | |type(string, int, boolean, array, object NomObjet...) description |
| − | | | + | |Définit la valeur de retour d'une fonction. |
|- | |- | ||
| − | |@ | + | |@static |
| | | | ||
| − | | | + | |Indique que l'objet est statique |
|- | |- | ||
|@since | |@since | ||
| − | |||
| − | |||
| − | |||
| − | |||
| | | | ||
| − | | | + | |Permet d'indiquer un numéro de version du produit à partir de laquelle l'objet sera utilisable |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
|- | |- | ||
|@throws | |@throws | ||
| | | | ||
| − | | | + | |Exception lancée par une méthode (voir aussi @throws). |
|- | |- | ||
|@todo | |@todo | ||
| | | | ||
| − | |Permet d'indiquer une | + | |Permet d'indiquer une description d'une tâche à accomplir prochainement sur l'objet. |
|- | |- | ||
|@var | |@var | ||
| − | |type | + | |type(string, int, boolean, array, object NomObjet) |
|Type de la propriété | |Type de la propriété | ||
|- | |- | ||
Version actuelle en date du 25 juin 2009 à 08:32
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 (les 2 étoiles en première ligne sont nécessaires à l'interprétation des commentaires comme étant du PHPDoc) : <source lang="php"> /**
* * */
</source>
Le premier paragraphe est dédié à la description courte de l'objet commenté, le deuxième à la description longue.
Pour préciser la version d'une fonction, l'auteur d'une classe ou encore le type de l'objet, on utilise des tags préfixés par le caractère arobas @ :
| Tag | Valeurs | Description |
|---|---|---|
| @abstract | L'objet est abstrait. | |
| @access | public, private or protected | Accessibilité de l'objet. |
| @author | Nom de l'auteur de l'objet <emaildelauteur@email.com> | Nom et adresse e-mail de l'auteur |
| @copyright | nom date | Copyright. |
| @deprecated | version | Indique que l'objet est obsolète. |
| @exception | Exception lancée par une méthode (voir aussi @throws). | |
| @global | type(string, int, boolean, array, object NomObjet...) $globalvarname | Variable globale. |
| @link | URL | URL associée à l'objet (redirection vers une documentation) |
| @package | nom du package | Nom du package de l'objet. |
| @param | type(string, int, boolean, array, object NomObjet...) [$varname] description | Décrit un paramètre à une fonction |
| @return | type(string, int, boolean, array, object NomObjet...) description | Définit la valeur de retour d'une fonction. |
| @static | Indique que l'objet est statique | |
| @since | Permet d'indiquer un numéro de version du produit à partir de laquelle l'objet sera utilisable | |
| @throws | Exception lancée par une méthode (voir aussi @throws). | |
| @todo | Permet d'indiquer une description d'une tâche à accomplir prochainement sur l'objet. | |
| @var | type(string, int, boolean, array, object NomObjet) | Type de la propriété |
| @version | Version de l'objet. |
Pour plus d'informations sur les tags, vous pouvez voir ces sites : Wikipedia PHPDoc, PHPDocumentor manuel...
