Comment documenter une application Rails ?

Question

Je viens de commencer à documenter une application Rails.Je sais que cela est en fait fait par rdoc, j'ai donc suivi quelques guides rdoc concernant la syntaxe, etc., mais je suis resté bloqué lorsque j'ai essayé de décrire les attributs des modèles, les validations et la relation entre les modèles, principalement parce que ces éléments font partie d'ActiveRecord.Je me demande donc s'il existe un guide ou une bonne pratique sur la façon de documenter une application Rails ou s'il me manque quelque chose ?

Je sais que je pourrais mettre tout cela dans la description de la classe, mais je me demande s'il existe un moyen plus étroitement lié à la déclaration elle-même (has_many, validates_presence_of, etc.) et qu'en est-il des attributs ?

Answer 1

Personnellement, je préfère YARD - http://yardoc.org , car il fait un meilleur travail dans la documentation à mon humble avis.Je ne sais pas s'il existe un gestionnaire spécifique pour Rails, mais il est assez facile d'en écrire un - http://yardoc.org/guides/extending-yard/writing-handlers.htmlUn bon exemple pourrait être le gestionnaire d'attributs - qui fait partie de la gemme yard :lib/yard/handlers/ruby/attribute_handler.rb

Answer 2

Rappelez-vous vos tests font partie de la documentation (pour les développeurs), en particulier si vous utilisez Concombre où les scénarios sont faciles à lire. Si vous gardez vos méthodes très court et il y a une méthode d'essai avec un nom descriptif par exemple « Devrait définir le nom des utilisateurs » Je trouve que je ne commentaires généralement pas besoin sur la méthode.

Validations ou d'autres parties de rails, je ne le document. Une partie d'être un développeur Rails est de comprendre comment ces travaux, je pense qu'il est une hypothèse juste qu'un autre mainteneur de votre code lu sur la route connaîtra, ou d'autres validations choses construites pour rails. Par cette même logique, si vous pouvez utiliser les fonctions des cadres ou des chemins heureux (pas dévier beaucoup) avec troisième code du parti [documenté], beaucoup de la documentation sera rédigée pour vous.