ruby - sirve - ¿Hay una buena referencia sólida para la sintaxis correcta de RDoc?

sintaxis de lenguaje ruby

Question

Estoy buscando una buena referencia sólida para la sintaxis RDoc adecuada. Recomendaciones? Parece que no puedo encontrar nada que muestre claramente:

1. Cómo documentar los métodos de clase y sus parámetros
2. Cómo documentar lo que hace un método de clase o clase.

Answer 1

Dado que RubyForge ha sido retirado , aquí hay un nuevo enlace:

http://ruby-doc.org/stdlib-2.5.1/libdoc/rdoc/rdoc/RDoc/Markup.html

Answer 2

Un ejemplo oficial de rdoc se puede encontrar here , con su fuente GitHub .

La documentación en rdoc.rubyforge.org parece ser más completa que la versión en rdoc.sourceforge.net (que por cierto tiene una fecha de modificación en 2003).

Además, hay una gran fuente de ejemplos: la documentación de Ruby core y stdlib. Por ejemplo, eche un vistazo a uno de los métodos de clase de la clase File :

File.atime (file_name) => time

Devuelve la última hora de acceso para el archivo nombrado como un objeto Time).

File.atime("testfile") #=> Wed Apr 09 08:51:48 CDT 2003

Puede ver el código fuente original, incluido el marcado RDoc, haciendo clic en la primera línea (en la página RDoc real, no en la cita que incluí en esta respuesta). En este caso, el método se implementó en C, pero el formato de RDoc es el mismo que si se implementara en Ruby:

/*
 *  call-seq:
 *     File.atime(file_name)  =>  time
 *  
 *  Returns the last access time for the named file as a Time object).
 *     
 *     File.atime("testfile")   #=> Wed Apr 09 08:51:48 CDT 2003
 *     
 */

A partir de esto, puede ver que call-seq: permite reemplazar el nombre del método y los parámetros con el texto de su elección, lo cual es muy útil para los métodos de clase. También muestra cómo puede mostrar el código de ejemplo en una fuente monoespaciada al sangrarlo, de manera similar a Markdown.