Ik ben op zoek naar een goede, solide referentie voor de juiste RDoc-syntaxis. Aanbevelingen? Ik kan niets vinden dat duidelijk laat zien:
- Hoe klassemethoden en hun parameters te documenteren
- Hoe documenteer je wat een klasse of klassemethode doet.
Antwoord 1, autoriteit 100%
Een officieel rdoc-voorbeeld is hierte vinden, met zijn GitHub-bron.
De documentatie op rdoc.rubyforge.orglijkt completer te zijn dan de versie op rdoc.sourceforge.net(die overigens een wijzigingsdatum van 2003 heeft).
Er is ook een geweldige bron met voorbeelden: de Ruby core en stdlib-documentatie. Bekijk bijvoorbeeld een van de klassenmethoden uit de Fileklasse:
Bestand.atime(bestandsnaam) => tijd
Retourneert de laatste toegangstijd voor de
genoemd bestand als een Time-object).
File.atime("testfile") #=> Wed Apr 09 08:51:48 CDT 2003
Je kunt de originele broncode, inclusief de RDoc-opmaak, bekijken door op de eerste regel te klikken (op de eigenlijke RDoc-pagina, niet in het citaat dat ik in dit antwoord heb opgenomen). In dit geval was de methode geïmplementeerd in C, maar de RDoc-opmaak is hetzelfde als wanneer deze in Ruby was geïmplementeerd:
/*
* 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
*
*/
Hieruit kun je zien dat call-seq:je de methodenaam en parameters laat vervangen door tekst naar keuze, wat erg handig is voor klassemethoden. Het laat ook zien hoe u voorbeeldcode in een monospaced lettertype kunt weergeven door het te laten inspringen, vergelijkbaar met Markdown.
Antwoord 2, autoriteit 69%
Sinds RubyForge met pensioen is, is hier een nieuwe link:
http://ruby-doc. org/stdlib-2.5.1/libdoc/rdoc/rdoc/RDoc/Markup.html