Comment documenter le code Ruby?

Existe-t-il certaines conventions de code lors de la documentation du code Ruby? Par exemple, j’ai l’extrait de code suivant:

require 'open3' module ProcessUtils # Runs a subprocess and applies handlers for stdout and stderr # Params: # - command: command line ssortingng to be executed by the system # - outhandler: proc object that takes a pipe object as first and only param (may be nil) # - errhandler: proc object that takes a pipe object as first and only param (may be nil) def execute_and_handle(command, outhandler, errhandler) Open3.popen3(command) do |_, stdout, stderr| if (outhandler) outhandler.call(stdout) end if (errhandler) errhandler.call(stderr) end end end end 

Cela suppose que c’est correct, mais peut-être y a-t-il des pratiques de documentation meilleures / supérieures?

Vous devez cibler votre documentation pour le processeur RDoc, qui peut trouver votre documentation et en générer du code HTML. Vous avez mis votre commentaire au bon endroit pour cela, mais vous devriez jeter un coup d’œil à la documentation RDoc pour en savoir plus sur les types de balises que RDoc sait formater. À cette fin, je reformaterais votre commentaire comme suit:

  # Runs a subprocess and applies handlers for stdout and stderr # Params: # +command+:: command line ssortingng to be executed by the system # +outhandler+:: +Proc+ object that takes a pipe object as first and only param (may be nil) # +errhandler+:: +Proc+ object that takes a pipe object as first and only param (may be nil) 

Je suggère fortement d’ utiliser RDoc . C’est à peu près la norme. Il est facile de lire les commentaires de code et de créer facilement une documentation Web pour votre projet.

Je suggère de connaître RDoc comme indiqué. Mais n’ignorez pas non plus le très populaire outil YARD A Ruby Document . Une grande partie de la documentation que vous verrez en ligne pour Ruby utilise Yard. RVM connaît Yard et l’utilise pour générer votre documentation sur votre machine si celle-ci est disponible.

RDoc serait toujours nécessaire, car Yard l’utilise.

Rails a des directives de documentation sur les API . C’est probablement un bon sharepoint départ.

Vous pouvez également vérifier TomDoc pour Ruby – Version 1.0.0-rc1.

http://tomdoc.org/

Le canonique est RDoc il est très similaire à celui que vous avez posté.

Voir la section exemple sur le lien que je vous ai envoyé

Voici la documentation du système de documentation ruby ​​(RDOC)