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/