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 string 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

Cette supposition est correcte, mais peut-être existe-t-il des pratiques de documentation meilleures / supérieures?

Vous devez cibler votre documentation pour le processeur RDoc, qui peut trouver votre documentation et générer du HTML à partir de celle-ci. Vous avez placé votre commentaire au bon endroit pour cela, mais vous devriez jeter un oeil à 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 string 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 du code et vous permet de créer facilement une documentation Web pour votre projet.

Je suggère de faire connaissance avec RDoc comme indiqué. Mais n'ignorez pas non plus l' outil très populaire 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 elle est disponible.

RDoc serait toujours requis, car Yard l'utilise.

Rails a quelques directives de documentation API . C'est probablement un bon point de 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 publié.

Voir l'exemple de section sur le lien que je vous ai envoyé

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