¿Cómo documentar el código Ruby?

201

¿Existen ciertas convenciones de código al documentar el código ruby? Por ejemplo, tengo el siguiente fragmento 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

¿Supongo que está bien, pero tal vez hay mejores prácticas de documentación superior?

ruby Apilado
fuente
shop.oreilly.com/product/9780596516178.do tiene un pequeño ejemplo en el código fuente. Mire en el listado del capítulo 2. Es como la respuesta aquí. He jugado con rdoc solo para mostrar el código fuente. Puede hacer que su extensión de archivo sea algo como my_code.rb a my_code.rb.txt y luego ejecutar rdoc en ella. > rdoc my_code.rb.txt, entonces no importará sobre las clases y los módulos porque rdoc representará html de todos modos. Diviértete con eso.
Douglas G. Allen

Respuestas:

198

Debe dirigir su documentación al procesador RDoc, que puede encontrar su documentación y generar HTML a partir de ella. Puso su comentario en el lugar correcto para eso, pero debería echar un vistazo a la documentación de RDoc para conocer los tipos de etiquetas que RDoc sabe formatear. Con ese fin, volvería a formatear su comentario de la siguiente manera:

  # 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
fuente
¿Cómo debo documentar que los parámetros outhandler y errhandler pueden ser nulos?
StackedCrooked
10
Las anotaciones de YARD pueden ser más potentes, pero hasta que se incluyan en la distribución estándar de Ruby en lugar de RDoc, sus anotaciones no son el estándar.
Ken Bloom
El enlace RDoc está roto intente esto: github.com/ruby/rdoc . Solicitaré editar la respuesta si todos están contentos con ese enlace.
Jordan Stewart
27

Recomiendo encarecidamente utilizar RDoc . Es más o menos el estándar. Es fácil leer los comentarios del código y le permite crear fácilmente documentación basada en la web para su proyecto.

Topher Fangio
fuente
24

Sugeriría conocer RDoc como se indica. Pero tampoco ignore la muy popular herramienta YARD A Ruby Document . Gran parte de la documentación que verá en línea para Ruby usa Yard. RVM conoce Yard y lo utiliza para generar su documentación en su máquina si está disponible.

RDoc aún sería necesario, ya que Yard lo usa.

vgoff
fuente
1
Habiendo usado principalmente C ++, Java, Scala y PHP, encuentro la @tagnotación muy familiar.
doub1ejack
1
Han pasado cuatro años y YARD ha evolucionado mucho. Es una pena que YARD todavía no esté incluido en Ruby. (Por cierto, la página de inicio de YARD acepta HTTPS.)
Franklin Yu
1
¡YARD parece ser más ligero que RDoc! Gracias :)
Constantin De La Roche
9

También puede consultar TomDoc para Ruby - Versión 1.0.0-rc1.

http://tomdoc.org/

onurozgurozkan
fuente
FWIW, este se especifica en la guía de estilo de GitHub - github.com/styleguide/ruby
Michael Easter
Gracias, tomdoc parece ser una buena fuente para las mejores prácticas actuales a la hora de documentar el código ruby. Responde el "cómo" y el "por qué" que aparentemente faltan en la documentación de rdoc.
Michael Renner
TomDoc no se ha mantenido actualizado. La última confirmación fue en mayo de 2012.
maasha
1
@maasha Para 2017, creo que la mejor apuesta, además de RDoc simple, sería YARD, ahora que analiza el contenido y crea algunos hipervínculos elegantes a clases y métodos.
Franklin Yu
2

El canónico es RDoc , es muy similar al que has publicado.

Vea la sección de muestra en el enlace que le envié

OscarRyz
fuente