Une façon idiomatique de documenter les defn de Clojure.

Question

Quelle est la manière idiomatique de documenter les définitions de fonctions ( defn ) en Clojure ? En particulier, devrions-nous utiliser " @param ", " @returns ", etc. pour documenter les paramètres, les valeurs de retour, etc.

Existe-t-il un moyen standard de spécifier les types de paramètres attendus (autre que les indications de type) dans ce langage à typage dynamique ?

Answer 1

Il ne semble pas y avoir une très forte tendance à utiliser les balises @param, bien que je pense qu'elles soient plus courantes. La balise @returns est peut-être moins applicable car il serait très logique de mettre toute la description de ce que fait la fonction sous la balise @returns.

En général, le code dans clojure.core s'en tient à la description de ce que fait la fonction et beaucoup d'entre elles commencent par le mot "return".

(defn rand-nth
  "Return a random element of the (sequential) collection. Will have
  the same performance characteristics as nth for the given
  collection."

Il y a une tendance dans le code idomatique de clojure à essayer d'utiliser les abstractions de la séquence de construction pour la plupart des fonctions, ainsi la chaîne de documentation de rand-nth pourrait ressembler à ceci :

(defn rand-nth
  "@Params: any seq
   @Returns a random element of the (sequential) collection. Will have
   the same performance characteristics as nth for the given
   collection."

qui ne dit pas grand-chose de plus que l'original.