¿Cómo se documenta el código de Ruby?

Question

¿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/mejores prácticas de documentación?

Answer 1

Debe orientar su documentación para el procesador RDoc, que puede encontrar su documentación y generar HTML a partir de ella. Ha puesto su comentario en el lugar correcto para eso, pero debería echarle un vistazo al RDoc documentation para conocer los tipos de etiquetas que RDoc sabe cómo formatear. Con ese fin, me gustaría volver a formatear el 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) 

Answer 2

La canónica es RDoc es muy similar a la que ha publicado.

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

Answer 3

Me altamente sugiere emplear 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.

Answer 4

Rails tiene algunos API Documentation Guidelines. Ese es probablemente un buen punto de partida.

Answer 5

Aquí está la documentación para el ruby documentation system (RDOC)

Answer 6

También puede comprobar TomDoc para Ruby - Versión 1.0.0-RC1.

http://tomdoc.org/

Answer 7

Yo sugeriría conocer RDoc como se dice. Pero no ignore la muy popular herramienta YARD A Ruby Document, también. Gran parte de la documentación que verá en línea para Ruby usa Yard. RVM conoce a Yard y lo usa para generar su documentación en su máquina si está disponible.

RDoc todavía se requerirá, ya que Yard lo usa.