Les commentaires peuvent apporter des précisions très importantes et très précieuses sur le contenu ou même le fonctionnement du code. Que ce soit sur un fichier, une classe, une méthode.
Mots-clés des commentaires
| Tag | Usage | Description |
|---|---|---|
| api | Methods | declares that elements are suitable for consumption by third parties. |
| author | Any | documents the author of the associated element. |
| category | File, Class | groups a series of packages together. |
| copyright | Any | documents the copyright information for the associated element. |
| deprecated | Any | indicates that the associated element is deprecated and can be removed in a future version. |
| example | Any | shows the code of a specified example file or, optionally, just a portion of it. |
| filesource | File | includes the source of the current file for use in the output. |
| global | Variable | informs phpDocumentor of a global variable or its usage. |
| ignore | Any | tells phpDocumentor that the associated element is not to be included in the documentation. |
| internal | Any | denotes that the associated elements is internal to this application or library and hides it by default. |
| license | File, Class | indicates which license is applicable for the associated element. |
| link | Any | indicates a relation between the associated element and a page of a website. |
| method | Class | allows a class to know which ‘magic’ methods are callable. |
| package | File, Class | categorizes the associated element into a logical grouping or subdivision. |
| param | Method, Function | documents a single argument of a function or method. |
| property | Class | allows a class to know which ‘magic’ properties are present. |
| property-read | Class | allows a class to know which ‘magic’ properties are present that are read-only. |
| property-write | Class | allows a class to know which ‘magic’ properties are present that are write-only. |
| return | Method, Function | documents the return value of functions or methods. |
| see | Any | indicates a reference from the associated element to a website or other elements. |
| since | Any | indicates at which version the associated element became available. |
| source | Any, except File | shows the source code of the associated element. |
| subpackage | File, Class | categorizes the associated element into a logical grouping or subdivision. |
| throws | Method, Function | indicates whether the associated element could throw a specific type of exception. |
| todo | Any | indicates whether any development activity should still be executed on the associated element. |
| uses | Any | indicates a reference to (and from) a single associated element. |
| var | Properties | |
| version | Any | indicates the current version of Structural Elements. |
Plus de détails : https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/index.html#tag-reference
Commentaire d’une fonction
Pour typer
Les paramètres des fonctions doivent être typés ainsi que le retour de la fonction. Voici les types primitifs :
/** * @param string * @param int * @param float * @param bool * @param array * @param callable * @param resource */
Il est également possible de typer un paramètre, le retour aussi, avec un objet. Admettons qu’on dispose d’un objet User pour représenter des utilisateurs, on peut écrire ceci :
/** * @param User */
Une fonction ne retourne pas forcément un résultat. Pour les fonctions n’ayant aucun retour, on pourra utiliser le mot-clé void.
/**
*
* @return void
*/
public function nomFonction(): void
{
}Pour les typer le contenu des tableaux
Il se peut qu’une fonction recevoir en paramètre un array, et qu’on connaisse le contenu de cet array. Il est dans ce cas possible de ne pas spécifier le type array mais plutôt le type qu’il de données qu’il contient, suivi d’accolades pour préciser qu’il s’agit d’un tableau. Exemples :
/**
* Fonction recevant un tableau d'objets DateTime
* @param \DateTime[] Tableau d'objets DateTime
*/
public function nomFonction(array $dates): void
{
}
/**
* Fonction recevant un tableau de noms
* @param string[] Tableau de noms
*/
public function nomFonction(array $best_players): void
{
}Deux types pour un même paramètre / retour
Il arrive qu’une fonction puisse retourner soit un type bien précis, soit null. Voici la syntaxe pour ce cas précis :
/**
*
* @return float|null Montant ou null
*/
public function nomFonction(): ?float {
}