Existe uma boa referência sólida para a sintaxe RDOC adequada?

Question

Estou procurando uma referência boa e sólida para uma sintaxe RDOC adequada. Recomendações? Não consigo encontrar nada que mostre claramente:

1. Como documentar os métodos de classe e seus parâmetros
2. Como documentar o que um método de classe ou classe faz.

Answer 1

Um exemplo oficial de rdoc pode ser encontrado aqui, com seu Fonte do github.

A documentação em rdoc.rubyforge.org parece ser mais completo do que a versão em rdoc.sourceforge.net (que aliás tem uma data modificada de 2003).

Além disso, há uma ótima fonte de exemplos: o núcleo do rubi e a documentação do stdlib. Por exemplo, dê uma olhada em um dos métodos de classe do File classe:

File.atime (file_name) => tempo

Retorna o último tempo de acesso para o arquivo nomeado como um objeto de tempo).

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

Você pode visualizar o código -fonte original, incluindo a marcação RDOC, clicando na primeira linha (na página RDOC real, não na citação que incluí nesta resposta). Nesse caso, o método foi implementado em C, mas a formatação RDOC é a mesma de que se tivesse sido implementada em 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 disso você pode ver isso call-seq: Permite substituir o nome do método e os parâmetros pelo texto da sua escolha, o que é muito útil para métodos de classe. Ele também mostra como você pode exibir o código de exemplo em uma fonte monoespactada recuando -a, semelhante ao Markdown.

Answer 2

Desde Rubyforge foi aposentado, aqui está um novo link:

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