Introduction à la documentation du code source PHP

Vidéo qui explique le rôle de PHPDocs
https://www.youtube.com/watch?time_continue=3&v=oa1iXzlTs04&feature=emb_logo

Tous les tags de PHPDocs
https://docs.phpdoc.org/latest/references/phpdoc/index.html

Les « docblocks »

En programmation, un « docblock » ou « DocBlock » est un commentaire formaté, utilisé dans le code source pour documenter un segment spécifique de code.
Chaque langage de programmation utilise un format spécifique pour écrire ses « docblock ».
En PHP les « docblock » utilisent le format PHPDoc.
Ils commencent par /** et se terminent par */.
En général, le signe * crée un filet vertical :

          /**
          * Ceci est un docblock
          */
      

Par convention, la première ligne sert de description courte de la fonction.
Elle peut être suffisante ou non. Si une description plus longue doit être apportée, il faut sauter une ligne entre les deux :

           /**
           * Ceci est la description courte, généralement sur une seule ligne
           *
           * Ceci est une description longue, facultative. Elle commence après la ligne
           * vide qui suit la description courte
           */
  

Les tags avec phpDocs

Les 'tags' sont comme des variables qui servent à décrire notre fonction.
Ils donnent des informations en plus par rapport aux descriptions courtes et longues.
Un tag s'écrit '@nom_du_tag' et il peut s'en suivre un certain contenu, en fonction du tag.

Les tags de PHPDocs utiles pour le projet

@param type $var [texte] : indique que le paramètre $var de la fonction est du type indiqué. On peut indiquer plusieurs possibilités avec | : int|string|null $var. Lorsqu'il y a plusieurs paramètres, et donc plusieurs fois le tag '@param', veillez à conserver le même ordre que les paramètres de la fonction, et les mêmes noms de variable.

@return type [texte] : pareil que @param pour les retours de la fonction.
Notez que si la fonction ne retourne rien (aucun mot clé return dans le code de la fonction), vous pouvez omettre @return, ou indiquer @return void.
Notez aussi que @return null est différent de @return void.
Vous pouvez cumuler plusieurs types de retours bien évidemment tel que @return void|int|string

Exemple PHPDocs pour les méthodes

/**
  * Méthode de récupération des enregistrements d'une table de la base de données.
  *
  * @param string $tableName Nom de la table de la base de données
  * @return array|null Retourne le tableau de résultats ou null si pas de résultats.
  */
 function getTableTuples($tableName)
 {
     ...
     return $result;
 }
 

Exemple PHPDocs pour les propriétés de vos classes PHP

Le minimum est d'ajouter une petite description de votre classe (Toujours au début des balises de commentaires).
Ensuite il est toujours intéressant d'utiliser les tags suivants :

• @package : est utilisé dans la documentation générée pour regrouper les classes et les pages procédurales de la même manière qu'un répertoire regroupe les fichiers associés.
• @author : permet de savoir qui a développer la classe dans l'équipe.
• @var : pour indiquer à quoi correspond chaque propriétés (champs, variables) de la classe

          /**
          * Class Article : classe mère des objets article. 
          * Contient toutes les méthodes de gestion d'un article (Creat/Read/Update/Delete)
          * 
          * @package MonProjetPHP
          * @author Prenom Nom
          */
          class Article {
          
          /**
          * @var int $id Identifiant unique de l'article 
          */
          public 	$id;
          /**
          * @var string $title  Titre de l'article
          */
          public 	$title;
          /**
          * @var string $texte  Texte de l'article
          */
          public 	$texte;
          /**
          * @var date $date Date de l'article
          */
          public 	$date;

          }