Comment le document code Ruby ?

Question

Y a-t-il certaines conventions de code documenter le code ruby ? Par exemple, j’ai l’extrait de code suivant :

Cette conjecture, c’est OK, mais peut-être y a-t-il des pratiques de documentation mieux/superior ?

Answer 1

Vous devriez cibler votre documentation pour le processeur RDoc, qui peut trouver votre documentation et générer le code HTML de celle-ci. Vous avez mis votre commentaire au bon endroit pour cela, mais vous devriez avoir un oeil à la documentation RDoc pour en savoir plus sur les types de balises que RDoc sait comment mettre en forme. À cette fin, je voudrais reformater votre commentaire comme suit :

Answer 2

Je serais très suggère d’utiliser RDoc. C’est à peu près la norme. Il est facile à lire les commentaires de code, et il vous permet de créer facilement des documents sur le web pour votre projet.

Answer 3

Je vous suggère d’apprendre à connaître les RDoc comme il est indiqué. Mais ne négligez pas le très populaire outil de Triage A Ruby Document . aussi bien. Beaucoup de la documentation en ligne, vous verrez pour Ruby utilise Yard. RVM sait Yard et l’utilise pour générer votre documentation sur votre machine si elle est disponible.

RDoc resterait nécessaire, comme le triage utilise.

Answer 4

Rails a quelques API Documentation Guidelines. C’est probablement un bon point de départ.

Answer 5

Vous pouvez également consulter TomDoc pour Ruby - Version 1.0.0-rc1.

http://tomdoc.org/