@inheritDoc vs {@inheritDoc}

Si vous lisez ceci, vous êtes sûrement tombé sur le commentaire

/**
 * {@inheritdoc}
 */

ou

/**
 * @inheritdoc
 */

dans une classe PHP.

Il s’agît de tags de phpDocumentor ; ce sont des mots-clefs permettant de rédiger une documentation sémantique. Par exemple

/**
 * @var string[]
 */
protected static $trustedProxies = array();  

nous indique que la propriété $trustedProxies est un tableau de chaînes de caractères grâce au tag @var.

inheritdoc quant à lui sert à hériter de la description d’une classe, interface, méthode ou propriété. Mais c’est un peu plus tordu.

{@inheritdoc} ou pas ?

La présence d’accolades indique un inline tag qui n’a de sens qu’au sein d’un texte où son contenu sera affiché. Un tag « normal » sera par contre auto-suffisant et placé sur sa propre ligne.

/**
 * @link http://perdu.com/
 */
Utilisation de link en mode « normal »
/**
 * Je suis {@link http://perdu.com/ perdu}.
 */
Utilisation de link en mode inline

Avoir un tag seul sur sa ligne veut donc dire qu’il ne devrait pas être inline. Mais ne nous arrêtons pas ici, je vous ai dit que c’était tordu.

Avec phpDocumentor, toute classe, interface, méthode ou propriété hérite par défaut de la documentation de son parent, ce qui veut dire qu’on a en théorie pas besoin de préciser qu’on en hérite. La seule utilisation justifiée d’inheritdoc est donc en mode inline, si on doit ajouter du contenu à la description du parent :

/**
 * Makes bars
 *
 * This class generates bars using the main algorithm.
 */
class bar  
{
}

/**
 * Makes chocolate bars
 *
 * There are two aspects to this class.
 * {@inheritdoc} In addition, the foo class
 * makes the bars chocolate
 */
class foo extends bar  
{
}

Vous pouvez voir plusieurs lignes dans les commentaires. La première est le résumé et celles dessous la description. Ce code

/**
 * {@inheritdoc}
 */

spécifie donc uniquement un résumé. Et devinez quoi ? Un résumé ne peut pas contenir d’inline tag. Du point de vue de phpDocumentor, ce code est donc invalide.

@inheritdoc ou pas ?

@inheritdoc n’est pas défini par phpDocumentor.

WTF

Mais alors on fait quoi ?

Nous avons donc le choix entre une syntaxe invalide qui n’apporte rien, et une syntaxe inexistante qui n’apporte rien. Pourquoi utiliser l’une ou l’autre alors ? Il y a en fait deux raisons :

  • Il semble que certains IDE nécessitent une indication explicite afin de maintenir l’héritage de la documentation.
  • Il est légitime d’expliciter l’héritage de la documentation pour indiquer qu’on ne l’a pas oubliée.

As such we are working to include a new (normal) tag in the PHPDoc Standard @inheritDoc that will serve that purpose.

Un futur tag @inheritdoc devrait apporter une solution satisfaisante, mais en attendant, aussi invalide qu’elle soit, la syntaxe à utiliser est

/**
 * {@inheritdoc}
 */

Faute de mieux.