RDoc
RDoc est l'outil utilisé par les développeurs Ruby pour générer une documentation à partir des commentaires dans le code. Il est très souvent décrié, car il oblige à mettre en forme les commentaires d'une certaine manière qui a tendance à rendre les commentaires difficilement lisibles directement dans le code. Il est également difficile de produire des templates différents pour la génération HTML de la documentation.
Il semblerait que 2010 soit l'année du grand changement pour cela. En 2008, la mode pour les développeurs Ruby était de faire son propre framework web, en 2009, ce fût les outils de tests/specs, et dans cette lignée, il semblerait que les outils de tests soient à la mode pour 2010. Je vais vous présenter les premiers candidats.
Yard
Yard n'est pas nouveau, mais revient en force. Il se place dans la continuité de RDoc en termes de fonctionnement, et cherche notamment à assurer la compatibilité avec RDoc. Il est ainsi utilisé par rdoc.info pour générer de jolies documentations à partir de dépôts git.
Mais Yard propose également une syntaxe alternative, en rupture avec celle de RDoc. Celle-ci est dans l'esprit de ce que javadoc ou doxygen propose : @param pour documenter un paramètre, @return pour la valeur de retour, @see pour faire une référence, etc.
Rocco
Rocco est un portage en Ruby de docco. Ce n'est pas exactement un outil de documentation, plus un outil de literate programming, mais il peut servir à documenter du code.
Son rendu HTML est sur deux colonnes. La colonne de droite affiche le code, coloré avec Pygments. La colonne de droite affiche les commentaires qui correspondent au code. La langage de markup utilisé pour les commentaires est Markdown, une syntaxe wiki généralement bien connue des développeurs.
TomDoc
Tom Preston-Werner, un des créateurs de Github, n'était pas satisfait par les solutions précédentes. Il cherchait un format qui soit facilement lisible directement dans le code, mais qui permette néanmoins de générer une documentation pour les utilisateurs qui leur conviennent : un template agréable, pas de méthodes privées... Il a donc proposé son propre format : TomDoc.
Je trouve que ce format convient pour lire les commentaires directement dans le code, mais je ne suis pas entièrement convaincu. Devoir marquer chaque méthode comme étant Public pour qu'elle apparaisse dans la documentation me semble contraignant, et remplacer attr_accessor par attr_reader plus attr_writer carrément casse-pieds.
Conclusion
Au final, ces différentes initiatives me paraissent intéressantes mais je ne sais pas trop laquelle choisir. Je pense que je vais attendre encore un peu que la situation se décante et que je puisse expérimenter les possibilités pour voir celle qui me convient le mieux.
