Un guide de style pour la référence d'API : une forme unique pour chaque entrée

Ce que c'est

Une entrée de référence décrit une fonction, un point de terminaison, un type ou une option. Un guide de style pour la documentation de référence est un court document interne qui fixe, pour chaque entrée, les sections et leur ordre, la forme de la phrase d'ouverture, et la formulation des informations récurrentes. Les recommandations de référence de Microsoft (citées) énumèrent les sections d'un article de référence dans un ordre fixe : titre et description, déclaration ou syntaxe, paramètres, valeur de retour, remarques, exemple, prérequis et voir aussi, avec les exceptions ou codes d'erreur lorsque l'élément peut en générer ; chaque paramètre porte son type de données et, le cas échéant, indique s'il est obligatoire ou facultatif, et la description ne doit pas se contenter de répéter le nom de l'élément. Les recommandations de Google pour les commentaires de référence d'API (citées) notent que seule la première phrase d'une description apparaît dans les sections de résumé et les index, si bien que l'information la plus importante doit y figurer, et qu'une dépréciation doit préciser ce qu'il faut utiliser à la place. OpenAPI (cité) sépare un summary, un énoncé court de ce que fait une opération, d'une description plus longue.

Pourquoi c'est important

La documentation de référence se lit par consultation ponctuelle, pas dans l'ordre. Un lecteur qui a appris où se trouve la valeur de retour dans une entrée s'attend à la trouver au même endroit dans la suivante ; un agent qui extrait des paramètres compte sur la même régularité. Les références générées (à partir de docstrings, d'OpenAPI, de commentaires de documentation) reproduisent la discipline de leur source ; le guide de style s'applique donc à la source.

Comment l'appliquer

• Première phrase : un énoncé complet de ce que fait l'élément, à la troisième personne, commençant par un verbe (« Renvoie le... », « Crée un... »), qui a un sens à lui seul dans un index.
• Paramètres : nom, type, obligatoire ou facultatif, valeur par défaut, plage ou format autorisé, et ce qui se passe aux limites. Un paramètre sans valeur par défaut indiquée a un comportement non documenté.
• Valeur de retour : type, signification, et les cas vide, nul ou introuvable.
• Erreurs : une ligne par condition, sous la forme « condition : erreur levée ou statut renvoyé » ; renvoyer vers le format d'erreur commun.
• Remarques : garanties d'ordre, idempotence, effets de bord, limites de débit, sûreté vis-à-vis des threads. Rien qui relève d'un tutoriel.
• Exemple : un appel minimal et exécutable avec son résultat ; le garder exécuté en intégration continue dans la mesure du possible.
• Dépréciation : le remplacement, la version depuis laquelle elle s'applique, et le plan de suppression, dans la première phrase.
• Terminologie : utiliser le terme privilégié par le glossaire pour chaque concept, et les mêmes unités et formats de date partout.

Pièges

Des résumés qui répètent le nom (« getUser : obtient l'utilisateur »). Décrire l'implémentation au lieu du contrat. Des contraintes énoncées uniquement en prose, alors qu'un validateur les applique différemment. Des exemples qui ne s'exécutent plus. Des ordres de section différents selon l'auteur, ce qui est précisément le problème que le guide vise à éliminer.