RDoc ist das Ruby-Dokumentationstool. Es bereitet Ruby- und C-Quelltext anhand von Kommentaren gut lesbar auf. Da RDoc-Formatierungsanweisungen sich logisch und inhaltlich gut lesbar in Kommentare einfügen, können sie einfach in diese eingebunden werden, ohne die Lesefähigkeit der Kommentare im Code zu beeinträchtigen.

Benutzung

Im Grunde funktioniert RDoc auch ohne Kommentare, leider ist der Output dementsprechend wenig informativ. RDoc läuft dann einfach nur die Klassen, Methoden und Module durch und gibt diese wahlweise in HTML, XML, ri, CHM oder neuerdings auch Darkfish-HTML aus. Um alle Dateien in einem Ordner und rekursiv auch den Unterordnern zu dokumentieren, kann man RDoc einfach in dem jeweiligen Verzeichnis ausführen:

cd pfad\zu\meinem\Verzeichnis
rdoc

Je nach Version von RDoc wird so entweder HTML (bis einschliesslich Version 2.2.1) oder Darkfish (ab Version 2.3.0) generiert. Will man nur eine bestimmte Datei dokumentieren, kann man diese einfach als Argument anhängen:

rdoc meine_datei.rb

Konsolenargumente

RDoc können verschiedene Argumente mitgegeben werden, die beispielsweise das Ausgabeformat ändern (-f) oder einen Titel festlegen (--title):

Formatierungsanweisungen in Kommentaren

• - und *

Ungeordnete Listen.

• 1. bis n.

Geordnete Listen. Verschachtelungen der Art 1.1.2 oder Ähnliches sind nicht möglich.

• [name]

Benannte Listen.

•  ::name

Einrückung.

• =text

Überschriften. Die Gleichzeichen werden nur vor dem Text gesetzt; je mehr Gleichheitszeichen, desto kleiner die Überschrift.

• ---

Horizontale Linie. Werden mehr Bindestriche gesetzt, wird die Linie dicker.

• _text_ und <i>text</i> und <em>text</em>

Sorgt für kursiven Text. Die Variante mit den Unterstrichen funktioniert nur bei einzelnen Wörtern.

• *text* und <b>text</b>

Fetter Text. Auch hier gilt: Die Kurzschreibweise geht nur bei einzelnen Wörtern.

• +text+ und <tt>text</tt>

Typschrift.

• Klassen-, Methoden- und Modulnamen werden automatisch verlinkt. Methodennamen können auch explizit in einer der Formen "Klasse#methode" (Instanzmethode) , "Klasse.methode" (Klassenmethode) oder "#methode" (Instanzmethode) angegeben werden.
• name[url]

Erzeugt einen Link, wobei name als der angezeigte Text verwendet wird. Direkt hingeschriebene Links werden mit ihrer URL verlinkt und angezeigt.

• #:stopdoc:

RDoc stoppt, falls es eine Zeile, die exakt wie diese aussieht (das # beginnt hier tatsächlich die Kommentarzeile). Alles was hiernach folgt, wird nicht mehr behandelt. Ausser, es folgt ein #:startdoc:.

• #:startdoc:

Dient zum Aufheben von #:stopdoc:. Ab hier wird wieder dokumentiert.

Spezielle Formatierungsanweisungen

Die folgenden Direktiven verändern nicht das Aussehen der Dokumentation, sondern erweitern ihren Informationsgehalt.

 :attr_reader:, :attr_writer:, :attr_accessor:

Diese Direktiven können genutzt werden, um metaprogrammatisch erzeugte Accessor-Methoden zu dokumentieren. Dieser Direktive muss eine leere Kommentarzeile mit doppelter Route # vorangehen.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

class A
  ##
  # :attr_accessor: x
  #Accesses the X coordinate. 
  
  #X coordinate. Writable via #x=. 
  attr_reader:x # :nodoc:
  
  def x=(val)
    raise(RangeError, "X has to be >= 0!") if x < 0
    @x = val
  end
  
end

 :call-seq:

Überschreibt die Methodendefinitionszeile. Diese Direktive kann auch in Kombination mit :method: und :document-method: (C-Parser) verwendet werden. Der Doppelpunkt am Anfang kann ausgelassen werden; :call-seq: benötigt auch keinen Whitespace vor sich (im Gegensatz zu den anderen Direktiven), dafür müssen jedoch die Definitionszeilen eingerückt werden, und um die Methodenbeschreibung anzuschließen, wird eine freie Kommentarzeile benötigt.

1
2
3
4
5
6
7
8

#call-seq: 
#  a ==> "a"
#  a(b) ==> b
#
#Es folgt die Methodenbeschreibung. 
def a(b = "a")
  return b
end

Ergebnis:

a ==> "a"
a(b) ==> b
---------
Es folgt die Methodenbeschreibung. 

 :doc:

Gegenteil von :nodoc:.

1
2
3
4
5
6

class A
  private
  def b # :doc:
    puts "c"
  end
end

 :Document-method:

Diese Direktive ist nur im C-Quelltext-Parser implementiert. Sie ist erforderlich, um C-Methoden dokumentieren zu können, die sich in anderen Dateien befinden. Wie bei :call-seq: können der vordere Doppelpunkt und führender Whitespace weggelassen werden.

 :method:

Dokumentiert eine Methode. Dies ist sehr nützlich für Methoden, die durch Metaprogrammierung erzeugt wurden. Dieser Direktive muss eine leere Kommentarzeile mit doppelter Raute # vorangehen.

1
2
3
4
5
6
7
8
9

class A 

  ##
  # :method: meine_meta_methode
  define_method(:meine_meta_methode) do
    #Code...
  end
  
end

Dies zeigt sogar den Sourcecode in Form der define_method-Anweisung an. Überfordert ist RDoc aber bei Konstrukten wie:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

class A
  
  #x method. 
  def x
    puts "x"
  end
  
  ##
  #  :method: foo
  #Writes hello. 
  
  ##
  #  :method: foofoo
  #call-seq: 
  #  foofoo() ==> nil
  #
  #Writes hello, too. 
  
  [:foo, :foofoo].each do |sym|
    define_method(sym) do
      puts "hello"
    end
  end
  
end

In diesem Fall wird eine der beiden Methoden verworfen, dafür bekommt die andere den define-method-Block als Source. Da das unerwünscht ist, müssen die :method:-Direktiven so verschoben werden, das RDoc keinen Zusammenhang zur #define-method-Anweisung erkennen kann:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

class A
  
  ##
  #  :method: foo
  #Writes hello. 
  
  ##
  #  :method: foofoo
  #call-seq: 
  #  foofoo() ==> nil
  #
  #Writes hello, too. 
  
  #x method. 
  def x
    puts "x"
  end
  
  [:foo, :foofoo].each do |sym|
    define_method(sym) do
      puts "hello"
    end
  end
  
end

Wie man an diesen Beispielen sieht, kann die :method:-Direktive mit der :call-seq:-Direktive kombiniert werden.

 :nodoc:

Dieses Element nicht dokumentieren.

1
2
3

def a # :nodoc:
  puts "b"
end

 :notnew:

Verhindert, dass RDoc initialize als Klasse.new dokumentiert.

 :singleton_method:

Wie :method:, jedoch wird die Methode als Singletonmethode - meistens also als Klassenmethode - dokumentiert.

 :yields:

Verändert die Anzeigeart des Methodennamens. Wenn RDoc auf eine Methode trifft, die yield verwendet, werden normalerweise die Namen der yield übergebenen Argumente übernommen.

1
2
3
4

def a
  b = 1
  yield b
end

a() {|b| ...}

1
2
3
4

def a # :yields: wasauchimmer
  b = 1
  yield b
end

a() {|wasauchimmer| ...}

Siehe auch

• Kommentar
• http://rdoc.sourceforge.net - Die Website von RDoc.
• http://www.ruby-doc.org - Die Dokumentation von Ruby verwendet ebenfalls RDoc.