Como documentar código Ruby?

201

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?

ruby StackedCrooked
fonte
shop.oreilly.com/product/9780596516178.do tem um bom exemplo no código-fonte. Veja a lista do capítulo 2. É quase como a resposta aqui. Eu brinquei com o rdoc apenas para mostrar o código fonte. Você pode tornar sua extensão de arquivo algo como my_code.rb para my_code.rb.txt e, em seguida, executar o rdoc nela. > rdoc my_code.rb.txt, então não importará classes e módulos porque o rdoc renderizará html para ele de qualquer maneira. Divirta-se com isso.
Douglas G. Allen

Respostas:

198

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)
Ken Bloom
fonte
Como devo documentar que os parâmetros outhandler e errhandler podem ser nulos?
StackedCrooked
10
As anotações de YARD podem ser mais poderosas, mas até que sejam incluídas na distribuição padrão do Ruby em vez de RDoc, suas anotações não são o padrão.
5609 Ken Bloom
O link RDoc está quebrado, tente o seguinte: github.com/ruby/rdoc . Solicitarei editar a resposta se todos estiverem satisfeitos com esse link.
Jordan Stewart
27

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.

Topher Fangio
fonte
24

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.

vgoff
fonte
1
Tendo usado principalmente C ++, Java, Scala e PHP, acho a @tagnotação muito familiar.
doub1ejack
1
Faz quatro anos e o YARD evoluiu bastante. É uma pena que YARD ainda não esteja incluído no Ruby. (A propósito, a página inicial do YARD aceita HTTPS).
Franklin Yu
1
YARD parece ser mais leve que RDoc! Obrigado :)
Constantin De La Roche
9

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

http://tomdoc.org/

onurozgurozkan
fonte
FWIW, este é especificado na guia de estilo GitHub - github.com/styleguide/ruby
Michael Páscoa
Obrigado, o tomdoc parece ser uma boa fonte para as melhores práticas atuais quando se trata de documentar o código ruby. Responde ao "como" e "por que" aparentemente ausente da documentação do rdoc.
Michael Renner
O TomDoc não foi atualizado. Última confirmação era de Maio de 2012.
maasha
1
@maasha Até 2017, acredito que a melhor aposta além do RDoc comum seria YARD, agora que ele analisa o conteúdo e cria alguns hiperlinks sofisticados para classes e métodos.
Franklin Yu
2

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

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

OscarRyz
fonte