Existe-t-il une bonne référence pour la syntaxe RDoc appropriée?

Question

Je cherche une bonne référence pour la syntaxe RDoc appropriée. Des recommandations? Je n'arrive pas à trouver quoi que ce soit qui montre clairement:

1. Comment documenter les méthodes de classe et leurs paramètres
2. Comment documenter ce qu'une classe ou une méthode de classe fait.

Answer 1

La documentation à rdoc.rubyforge.org semble être plus complète que la version à rdoc.sourceforge.net (qui a d'ailleurs en 2003, date de modification).

Aussi, il est une grande source d'exemples: Ruby et stdlib de la documentation. Par exemple, jetez un oeil à l'une des méthodes de la classe de l' File classe:

Fichier.atime(file_name) => temps

Retourne le dernier temps d'accès pour les nom de fichier comme un objet de Temps).

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

Vous pouvez afficher le code source d'origine, y compris la RDoc de balisage, en cliquant sur la première ligne (dans le RDoc page, pas dans la citation que j'ai inclus dans cette réponse). Dans ce cas, la méthode a été implémentée en C, mais le RDoc mise en forme est la même que si elle était mise en œuvre 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
 *     
 */

À partir de ce que vous pouvez voir qu' call-seq: vous permet de remplacer le nom de la méthode et des paramètres avec le texte de votre choix, ce qui est très utile pour les méthodes de la classe. Il montre également comment vous pouvez afficher un exemple de code dans une police à chasse fixe par l'indentation, similaire à celle de Markdown.

Answer 2

Depuis que RubyForge a pris sa retraite , voici un nouveau lien:

http://ruby-doc.org/gems/docs/r/rdoc-4.1.1/RDoc/Markup.html