Documentation des fonctions

Éléments d'une fonction à documenter

La fonction est définitivement l'élément le plus complexe à documenter. En effet, une fonction peut être déclaré avec de nombreuses configurations différentes d'une fonction à l'autre. Entres autres, les fonctions peuvent contenir une certaine quantité de paramètres ou encore avoir une valeur de retour. En plus de la description de la fonction, ces éléments doivent être documenté pour être en mesure de bien indiquer aux autres programmeurs comment utiliser votre fonction.

Comme pour les classes et variables de classe, les commentaires de documentation des fonctions doivent se trouver juste au dessus de celles-ci.

Fonction avec paramètres

La documentation d'une fonction contenant des paramètres se fait de la façon suivante:

Fonction avec valeur de retour

La documentation d'une fonction contenant une valeur de retour se fait de la façon suivante:

Autres variantes

Une fonction ne contenant pas de paramètres ou de valeur de retour pourra simplement avoir un commentaire ayant sa description. Les instructions de paramètre et de valeur de retour n'ont donc pas besoin d'y être ajouté.

De la même façon, une fonction qui possède des paramètres et une valeur de retour pourra combiner les techniques ci-dessus pour bien documenter ceux-ci. En règle général, on mettra les instructions pour les paramètres avant l'instruction pour la valeur de retour dans le commentaire de documentation.

Contructeurs

Dans la plupart des langages orientés objets, vous aurez aussi à documenter les constructeurs de classe. Les constructeurs se documente de la même façon qu'une fonction, à l'exception qu'ils ne peuvent pas avoir de valeur de retour. Pour le reste, c'est exactement pareil.