Le fonctionnement de la documentation technique officielle de WordPress

R.I.P. le vieux Codex… et Bonjour DevHub !

Le vénérable Codex WordPress n’est plus maintenu et il est maintenant en bonne partie obsolète. Cet outil a été abandonné depuis maintenant quelques années et ses pages redirigent progressivement vers DevHub, le site de la documentation de WordPress : developer.wordpress.org

Les redirections 301 sont mises en place au fur et à mesure de la migration du codex vers DevHub. Dans tous les cas, le Codex étant obsolète, il ne faut plus l’utiliser mais lui préférer les pages DevHub. De toutes manières, ce sont progressivement les pages DevHub qui remontent en premier sur Google.

À noter : cet article parle de la documentation technique de WordPress, nommée DevHub. Il existe également une documentation sur l’utilisation de WordPress, nommée HelpHub, mais c’est une toute autre plateforme, accessible à l’adresse fr.wordpress.org/support.

Comment lire la documentation sur developer.wordpress.org

Prenons par exemple une fonction de base de WordPress au hasard : get_the_time().

Sur la fiche developer.w.org, on retrouvera plusieurs sections :

• Le nom de la fonction
• Une description courte
• Une description longue (quand nécessaire)

• Les paramètres d’entrée de la fonction (si la fonction dispose de paramètres) :

• Les éléments retournés par la fonction (si la fonction est sensée retourner quelque chose) :

• La source de la fonction dans le cœur WordPress, avec les éléments suivants :
  • Le fichier dans lequel la fonction est déclarée (lien cliquable vers la liste de toutes les fonctions déclarées dans ce fichier).
  • Le code de la fonction.
  • Un bouton permettant de voir le code source en entier.
  • Un lien “View on Trac” pour voir la fonction au sein du fichier où elle est déclarée sur Trac, sur le dépôt du code source de WordPress.

• Le changelog : il s’agit de la liste des différentes modifications faites sur la fonction et de la version de WordPress correspondant à chaque modification. Cela permet de savoir quand une fonction a été introduite dans le cœur WP et quand est-ce qu’elle a été modifiée.

• Une section Related composée de deux sous-sections :
  • Uses : les autres fonctions utilisées par la fonction en question
  • Used by : les autres fonctions qui utilisent la fonction en question

• User contributed notes : des sortes de commentaires permettant aux développeuses et aux développeurs de proposer des exemples d’utilisation et autres remarques concernant la fonction.

Contribution : les User Contributed Notes

N’hésitez pas à proposer des user contributed notes ! Vous pouvez ajouter des commentaires concernant l’utilisation d’une fonction, ou des exemples d’usage avancé.

D’une part c’est un excellent moyen de contribuer à WordPress, d’autre part vous serez peut-être content de retrouver votre propre commentaire la prochaine fois que vous chercherez de la documentation sur cette fonction !

Les notes sont validées manuellement par l’équipe de documentation de WordPress. Si vous proposez une note, n’hésitez pas à me solliciter sur mon compte Twitter (ou sur le Slack WPFR) pour la valider vu que je m’occupe de leur modération. 😃 Je fais généralement une passe de modération tous les 15 jours.

N’hésitez donc pas à prendre quelques dizaines de minutes pour proposer une user contributed note. 🎖

Comment fonctionne la génération de la documentation de WordPress sur developer.w.org

La génération de la documentation des fonctions, classes, hooks, etc sur developer.wordpress.org est pour l’essentiel intégralement automatisée !

Cela fonctionne à l’aide de la syntaxe DocBlock, qui permet de définir la documentation d’un code source PHP sous la forme de blocs de commentaires. Ensuite, ces commentaires sont automatiquement scannés afin de générer la documentation de WordPress.

Pour certaines fonctions, hooks ou classes particulièrement importantes, la génération de la documentation est semi-automatique : DocBlock permet de remonter une base de documentation et des contenus complémentaires sont ajoutés en back-office de dev.wordpress.org :

Exemple de documentation d’une fonction WP

Si l’on reprend l’extemple de get_the_time(), voici les commentaires PHP qui se trouvent juste avant la fonction (située dans le fichier wp-includes/general-template.php) :

/**
 * Retrieve the time at which the post was written.
 *
 * @since 1.5.0
 *
 * @param string      $d    Optional. Format to use for retrieving the time the post
 *                          was written. Either 'G', 'U', or php date format defaults
 *                          to the value specified in the time_format option. Default empty.
 * @param int|WP_Post $post WP_Post object or ID. Default is global $post object.
 * @return string|int|false Formatted date string or Unix timestamp if `$d` is 'U' or 'G'. False on failure.
 */
function get_the_time( $d = '', $post = null ) {
    // Contenu de la fonction
}

• La première ligne contient la description courte
• La ligne suivante (ici inexistante) contient la description longue
• Le ligne commençant par @since génère les lignes de la section Changelog. Il s’agit des versions de WP sur lesquelles des changements on été faits sur cette fonction.
• La ou les ligne(s) commençant par @param contiennent les paramètres d’entrée de la fonction.
• La ligne commençant par @return contient ce que retourne la fonction.

La syntaxe DocBlock utilisée dans le cadre du logiciel WordPress est spécifiquement détaillée dans le handbook du Core WordPress.

À noter : il existe également une syntaxe de documentation spécifique à JavaScript.

Développeuses et développeurs : documentons le code que nous produisons !

Lors de la création d’une fonction, d’un hook ou d’une classe sur un thème ou sur une extension que nous avons créé, il est intéressant de documenter ce nouveau code en utilisant la syntaxe DocBlock. Il n’est pas strictement nécessaire d’utiliser l’ensemble des règles qui s’appliquent à WP mais au minimum, il est intéressant de les utiliser pour documenter :

• La description courte (une ligne) du code source concerné
• Les paramètres que l’on peut passer dans la fonction (en entrée) et leur valeur par défaut
• Ce que retourne la fonction (en sortie)

Générer une documentation automatiquement avec WP à partir des commentaires DocBlock

Pour générer les pages de DevHub, une extension WordPress est utilisée sur WordPress.org. Cette extension scanne le cœur WP à la recherche de DocBlocks pour en créer la documentation. Pour chaque fonction, classe ou hook disposant d’un DocBlock, une page de documentation est automatiquement créée en utilisant les CPT que cette extension créée.

Rendu en back-office sur le site developer.wordpress.org :

Cette extension est open-source et installable sur n’importe quel site WP. Elle est disponible sur GitHub :

Je sais qu’elle est notamment utilisée par nos amis de Polylang pour générer leur documentation à destination des développeuses et des développeurs. 😎