Como documentar código Ruby?

Existem certas convenções de código ao documentar o código ruby? Por exemplo, eu tenho o seguinte trecho de código:

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

Acho que está tudo bem, mas talvez haja práticas de documentação melhores / superiores?

Você deve direcionar sua documentação para o processador RDoc, que pode encontrar sua documentação e gerar HTML a partir dela. Você colocou seu comentário no lugar certo para isso, mas deve dar uma olhada na documentação do RDoc para aprender sobre os tipos de tags que o RDoc sabe como formatar. Para esse fim, reformato seu comentário da seguinte maneira:

  # 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)

Eu altamente sugeriria usar RDoc . É praticamente o padrão. É fácil ler os comentários do código e permite criar facilmente documentação baseada na Web para o seu projeto.

Eu sugeriria conhecer o RDoc como está indicado. Mas não ignore a muito popular ferramenta YARD A Ruby Document . Muita da documentação que você verá online para Ruby usa Yard. O RVM conhece a Yard e a utiliza para gerar sua documentação em sua máquina, se estiver disponível.

O RDoc ainda seria necessário, como o Yard o usa.

O Rails possui algumas diretrizes de documentação da API . Esse é provavelmente um bom ponto de partida.

Você também pode verificar o TomDoc for Ruby - Versão 1.0.0-rc1.

http://tomdoc.org/

O canônico é RDoc , é muito parecido com o que você postou.

Veja a seção de amostra no link que enviei a você

Aqui está a documentação para o sistema de documentação ruby ​​(RDOC)