Rdoc. Documentar programas Ruby.

¿Que es Rdoc?

RDoc es el generador de documentación de Ruby por defecto a partir de la version 1.8.2, diseñado por Dave Thomas. Analiza el código fuente Ruby generando una estructura de las colecciones de paquetes para los objetos y métodos. Es capaz de realizar un análisis sintáctico recursivo de un directorio y encontrar todos los archivos .rb, .rbw y .c en busca de comentarios encima de la definición de cada función y al inicio del fichero. El formato de salida es HTML y crea el archivo en el subdirectorio doc.

RDOC es útil incluso si el código fuente de destino no contiene comentarios explícitos. RDOC aún analizará las clases, módulos y métodos, y la lista de ellos en los archivos generados de la API.

RDOC también proporciona el motor para la creación de archivos Ruby ri. ri es la versión de Ruby de páginas de manual, que sirve de información de la API de la línea de comandos.

RDOC y ri actualmente son mantenidos por Eric Hodel y Ryan Davis.

Instalación con RVM

$ gem install rdoc

Ejecución

Para ejecutar RDoc hay que llamarlo con el siguiente comando rdoc y se pueden utilizar algunos flags:

• --main [PATH a un fichero], hará que el fichero apuntado sea el que aparezca como inicio en la documentación generada.
• --all, incluye también métodos privados en la documentación (por defecto solo incluye los públicos).
• --op [PATH a un directorio], utiliza este directorio para guardar la documentación en lugar de "doc".
• --o [PATH a un directorio], directorio origen, sino toma desde donde se le llama.
• --inline-source, incluye el código fuente de cada método en la documentación.

Ejecución con RVM

$ rdoc + tabulador
rdoc                               rdoc-ruby-1.8.7-p302@global
rdoc-data                          rdoc-ruby-1.8.7-p302@gemset2l
rdoc-ruby-1.8.7-p302               rdoc-ruby-1.9.2-p0
rdoc-ruby-1.8.7-p302@gemset1       rdoc-ruby-1.9.2-p0@global

Documentar nuestra aplicación Rails

rake doc:app

Generating HTML...

Files: 28
Classes: 17
Modules: 12
Methods: 108
Elapsed: 1.914s


Reglas basicas de marcado

• = cabecera de nivel 1.
• == cabecera de nivel 2.
• === Cabecera de nivel 3
• etiqueta:: para hacer referencia a una etiqueta o label
• * o - crea un elemento de una lista.
• # crea un elemento de una lista numerada.
• Con las palabras se puede hacer: *negrita*, _itálica_ y +codigo+.
• Tambien podemos usar <b></b> , <em></em> , <tt></tt>
  

Otras marcas:

• :title: MyClase
• :include: Incluye el contenido de un archivo especifico en la documentación. La sangría se ajustara para tener consistencia.
• :main: Establecer la página inicial que aparecen en la salida.
• :nodoc: No documentamos algo
• :nodoc: all No se documentara algo, ni lo que contenga. (recursivo)
  

Ejemplo práctico

# = ejemplo_rdoc.rb
#
# Autor::   Daniel Martin Maldonado
# Web::     http://www.elcodigok.com.ar
#
# == Ejemplo
#
# Con este pequeño ejemplo pretendemos:
# - Dar a conocer la herramient *rdoc*
# - Mostrar como se utilizan los Markpu
# - Mostrar la sencillez de su implementación en pequeños y grandes proyectos
#
# === Clase Persona
#
# Definición de la clase _Persona_ compuesta por
# * metodo initialize
# * metodo saludar
#

class Persona
def initialize(nombre)
@nombre = nombre
end
def saludar
puts "Hola, me llamo #{@nombre}"
end
end

daniel = Persona.new("Daniel")
daniel.saludar

Para obtener su documentación podemos hacerlo de la siguiente manera:

$ rdoc --main -o documento ejemplo_rdoc.rb --op ~/destino_ejemplo_rdoc/

Parsing sources with 2 thread(s)...
100% [ 1/ 1] ejemplo_rdoc.rb
Generating Darkfish...
Files: 1
Classes: 1
Modules: 0
Methods: 2
Elapsed: 0.4s


Fuentes
wikipedia spejman maestrosdelweb rdoc rdoc v3 elcodigok handy rails

Otro ejemplo
http://socios.aditel.org/~andreu/ruby/rdoc_example/
http://socios.aditel.org/~andreu/ruby/apuntes.pdf