Die Programmiersprache Ruby (German Edition)

trennt.
    2.1.1 Kommentare
    Kommentare beginnen in Ruby mit einem
#
-Zeichen und gehen weiter bis ans Ende der Zeile. Der Ruby-Interpreter ignoriert das
#
-Zeichen und sämtlichen Text, der ihm folgt (aber er ignoriert nicht das Zeilenumbruchzeichen, das Whitespace mit Bedeutung ist und als Anweisungsabschluss dienen kann). Wenn ein
#
-Zeichen innerhalb eines String-Literals oder eines regulären Ausdrucks (siehe Kapitel 3 ) erscheint, ist es einfach Teil des Strings oder des regulären Ausdrucks und leitet keinen Kommentar ein:
# Diese ganze Zeile ist ein Kommentar
x = "#Dies ist ein String" # Und dies ist ein Kommentar
y = /#Dies ist ein regulärer Ausdruck/ # Hier ein weiterer Kommentar
    Mehrzeilige Kommentare werden normalerweise geschrieben, indem jede Zeile mit einem separaten
#
-Zeichen beginnt:
#
# Diese Klasse repräsentiert eine komplexe Zahl.
# Trotz ihres Namens ist sie überhaupt nicht komplex.
#
    Beachten Sie, dass Ruby kein Äquivalent zum
/*...*/
-Kommentar im C-Stil besitzt. Es gibt keine Möglichkeit, einen Kommentar in der Mitte einer Codezeile einzubetten.
    2.1.1.1 Eingebettete Dokumente
    Ruby unterstützt einen weiteren Stil mehrzeiliger Kommentare, die als eingebettete Dokumente ( embedded documents ) bezeichnet werden. Sie starten in einer Zeile, die mit
=begin
anfängt, und reichen bis (einschließlich) zu einer Zeile, die mit
=end
beginnt. Sämtlicher Text, der hinter
=begin
oder vor
=end
steht, ist Teil des Kommentars und wird ebenfalls ignoriert, aber dieser zusätzliche Text muss durch mindestens ein Leerzeichen von
=begin
beziehungsweise
=end
getrennt werden.
    Eingebettete Dokumente sind eine bequeme Methode, um lange Codeblöcke auszukommentieren, ohne jeder einzelnen Zeile ein
#
-Zeichen voranzustellen:
=begin Jemand muss den defekten Code hier unten reparieren!
Sämtlicher Code hier ist auskommentiert
=end
    Beachten Sie, dass eingebettete Dokumente nur funktionieren, wenn das
=
-Zeichen jeweils das erste Zeichen der Zeile ist:
# =begin Das begann vorher einen Kommentar. Nun ist es selbst auskommentiert!
Der Code hier ist nicht mehr auskommentiert
# =end
    Wie ihr Name vermuten lässt, können eingebettete Dokumente verwendet werden, um lange Dokumentationsblöcke in ein Programm einzuschließen oder um Quellcode einer anderen Sprache (etwa HTML oder SQL) in ein Ruby-Programm einzubetten. Eingebettete Dokumente sind üblicherweise dafür gedacht, von irgendeinem Nachbearbeitungstool verwendet zu werden, das den Ruby-Quellcode durchläuft, und üblicherweise folgt dem
=begin
ein Bezeichner, der anzeigt, für welches Tool der Kommentar gedacht ist.
    2.1.1.2 Dokumentationskommentare
    Ruby-Programme können eingebettete API-Dokumentation als speziell formatierte Kommentare enthalten, die Methoden-, Klassen- und Moduldefinitionen vorausgehen. Sie können diese Dokumentation mit dem Tool ri lesen, das weiter oben in „1.2.4 Die Ruby-Dokumentation mit ri lesen“ beschrieben wurde. Das Tool rdoc extrahiert Dokumentationskommentare aus dem Ruby-Quellcode und formatiert sie als HTML oder bereitet sie zur Anzeige in ri vor. Die Dokumentation des Tools rdoc würde über den Rahmen dieses Buches hinausgehen; Details finden Sie in der Datei lib/rdoc/README im Ruby-Quellcode.
    Dokumentationskommentare müssen unmittelbar vor dem Modul, der Klasse oder der Methode stehen, deren API sie dokumentieren. Sie werden üblicherweise als mehrzeilige Kommentare geschrieben, in denen jede Zeile mit
#
beginnt, aber sie können auch als eingebettete Dokumente geschrieben werden, die mit
=begin rdoc
anfangen. (Das Tool rdoc verarbeitet diese Kommentare nicht, wenn Sie das »
rdoc
« weglassen.)
    Das folgende Beispiel demonstriert die wichtigsten Formatierungselemente der Auszeichnungskommentare in Ruby-Dokumentationskommentaren; eine detaillierte Beschreibung der Grammatik befindet sich in der oben erwähnten README -Datei:
#
# Rdoc-Kommentare verwenden eine einfache Auszeichnungsgrammatik,
# ähnlich derjenigen, die in Wikis zum Einsatz kommt.
#
# Trennen Sie Absätze durch eine Leerzeile.
#
# = Überschriften
#
# Überschriften beginnen mit einem Gleichheitszeichen.
#
# == Unter-Überschriften
# Die Zeile oben erzeugt eine Unter-Überschrift.
# === Unter-Unter-Überschrift
# Und so weiter.
#
# = Beispiele
#
# Eingerückte Zeilen werden wortgetreu in Codeschrift angezeigt.
# Passen Sie auf, dass Sie Überschriften und Listen nicht einrücken.
#
# = Listen und Schriften
#
# Listenelemente beginnen mit * oder -.
#