tutorial - ¿Cómo documentar el código de Ruby?

ruby wikipedia

Question

¿Hay algunas convenciones de código al documentar el código de 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

Esta es una suposición, ¿está bien, pero quizás haya mejores / mejores prácticas de documentación?

Answer 1

Aquí está la documentación para el sistema de documentación Ruby (RDOC)

Answer 2

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 echar un vistazo a la documentación de RDoc para conocer los tipos de etiquetas que RDoc sabe cómo formatear. Con ese fin, cambiaría el formato de tu 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 3

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

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

Answer 4

Rails tiene algunas Pautas de documentación de API . Ese es probablemente un buen punto de partida.

Answer 5

Sugeriría conocer RDoc como se dice. Pero no 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 a Yard y lo usa para generar su documentación en su máquina si está disponible.

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

Answer 6

Sugeriría usar 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 7

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

http://tomdoc.org/