Cómo documentar el código Ruby?

¿Hay ciertas convenciones de código cuando se documenta 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

Esta conjetura esto está bien, pero tal vez hay prácticas de documentación mejores/superiores?

 173
ruby
Author: StackedCrooked, 2009-11-05
Source

7 answers

Debe dirigir su documentación al procesador RDoc, que puede encontrar su documentación y generar HTML a partir de ella. Has puesto tu comentario en el lugar correcto para eso, pero deberías echar un vistazo a la documentación RDoc para aprender sobre los tipos de etiquetas que RDoc sabe cómo formatear. Con ese fin, reformatearía 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)
 175
Author: Ken Bloom,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2009-11-05 16:01:28

Me gustaría altamentesugerir el uso de 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.

 24
Author: Topher Fangio,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2013-10-05 12:36:55

Yo sugeriría conocer RDoc como se dice. Pero no ignore la muy popular herramienta YARD A Ruby Document, también. Mucha 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 seguiría siendo necesario, ya que Yard lo usa.

 17
Author: vgoff,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2018-07-22 00:48:25

Rails tiene algunas Pautas de documentación de la API . Probablemente sea un buen punto de partida.

 15
Author: Hank Gay,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2013-02-06 14:24:17

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

Http://tomdoc.org/

 8
Author: onurozgurozkan,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2012-12-14 14:42:08

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

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

 2
Author: OscarRyz,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2009-11-05 16:00:21

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

 2
Author: jrhicks,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2009-11-05 16:03:14