Dokumentationsleitfaden

Dieser Leitfaden bespricht Empfehlungen zur Dokumentation von Klassen, Modulen und Methoden im Ruby-Kern und in der Ruby-Standardbibliothek.

Dokumentation generieren

Die meisten Ruby-Dokumentationen leben in den Quelldateien und sind im RDoc-Format verfasst.

Einige Seiten befinden sich im Ordner doc und können entweder im .rdoc- oder im .md-Format verfasst sein, bestimmt durch die Dateierweiterung.

Um die Ausgabe von Dokumentationsänderungen in HTML im Verzeichnis {build folder}/.ext/html zu generieren, führen Sie Folgendes in Ihrem Build-Verzeichnis aus:

make html

Wenn Sie kein Build-Verzeichnis haben, folgen Sie der Schnellstartanleitung bis Schritt 4.

Anschließend können Sie Ihre Änderungen in Ihrem Browser durch Öffnen der Datei {build folder}/.ext/html/index.html in der Vorschau anzeigen lassen.

Das Ziel der Ruby-Dokumentation ist es, die wichtigsten und relevantesten Informationen in kürzester Zeit zu vermitteln. Der Leser sollte schnell die Nützlichkeit des Quellcodes verstehen und wissen, wie er ihn verwendet.

Zu wenig Informationen zu geben ist schlecht, aber unwichtige Informationen oder unnötige Beispiele zu liefern ist auch nicht gut. Nutzen Sie Ihr Urteilsvermögen darüber, was der Benutzer wissen muss.

Allgemeine Richtlinien

Beachten Sie, dass der Leser möglicherweise kein fließendes Englisch spricht.
Schreiben Sie kurze, deklarative oder imperative Sätze.
Gruppieren Sie Sätze in (idealerweise kurze) Absätze, die jeweils ein einzelnes Thema behandeln.
Organisieren Sie Material mit Überschriften.
Beziehen Sie sich mit Links auf maßgebliche und relevante Quellen.
Verwenden Sie einfache Zeitformen: Simple Präsens, Simple Vergangenheitsform, Simple Futur.
Verwenden Sie einfache Satzstrukturen, keine zusammengesetzten oder komplexen Strukturen.
Vermeiden Sie
- Übermäßige, durch Kommas getrennte Phrasen; erwägen Sie eine Liste.
- Idiomatische Ausdrücke und kulturspezifische Referenzen.
- Übermäßige Verwendung von Überschriften.
- Verwendung von US-ASCII-inkompatiblen Zeichen in C-Quelldateien; siehe Zeichen unten.

Zeichen

Verwenden Sie nur US-ASCII-kompatible Zeichen in einer C-Quelldatei. (Wenn Sie andere Zeichen verwenden, wird Ihnen die Ruby CI sanft Bescheid geben.)

Wenn Sie ASCII-inkompatible Zeichen in die Dokumentation einer C-kodierten Klasse, eines Moduls oder einer Methode einfügen möchten, gibt es Workarounds, die neue Dateien doc/*.rdoc beinhalten.

Für die Klasse Foo (definiert in Datei foo.c), erstellen Sie die Datei doc/foo.rdoc, deklarieren Sie class Foo; end und platzieren Sie die Klassendokumentation über dieser Deklaration.
```
# Documentation for class Foo goes here.
class Foo; end
```
Ebenso erstellen Sie für das Modul Bar (definiert in Datei bar.c) die Datei doc/bar.rdoc, deklarieren Sie module Bar; end und platzieren Sie die Moduldokumentation über dieser Deklaration.
```
# Documentation for module Bar goes here.
module Bar; end
```
Für eine Methode ist es anders. Die Dokumentation einer Methode wie oben beschrieben deaktiviert die Funktion "Klicken zum Umschalten des Quellcodes" in der gerenderten Dokumentation.

Daher ist es am besten, die Dateiinclusion zu verwenden.
- Behalten Sie die call-seq im C-Code bei.
- Verwenden Sie die Dateiinclusion (:include:), um Text aus einer .rdoc-Datei einzufügen.
Beispiel
```
/*
 *  call-seq:
 *    each_byte {|byte| ... } -> self
 *    each_byte               -> enumerator
 *
 *  :include: doc/string/each_byte.rdoc
 *
 */
```

RDoc

Ruby wird mit RDoc dokumentiert. Informationen zur RDoc-Syntax und zu den Funktionen finden Sie in der RDoc Markup Reference.

Ausgabe von `irb`

Für Codebeispiele sollten Sie interaktives Ruby, irb, in Betracht ziehen.

Für ein Codebeispiel, das irb-Ausgabe enthält, sollten Sie erwägen, # => ... in aufeinanderfolgenden Zeilen auszurichten. Die Ausrichtung kann manchmal die Lesbarkeit verbessern.

a = [1, 2, 3] #=> [1, 2, 3]
a.shuffle!    #=> [2, 3, 1]
a             #=> [2, 3, 1]

Überschriften

Organisieren Sie eine lange Diskussion für eine Klasse oder ein Modul mit Überschriften.

Verwenden Sie keine formellen Überschriften in der Dokumentation für eine Methode oder Konstante.

In dem seltenen Fall, dass überschriftenähnliche Strukturen innerhalb der Dokumentation für eine Methode oder Konstante benötigt werden, verwenden Sie fetten Text als Pseudobeschriftungen.

Leerzeilen

Eine Leerzeile beginnt einen neuen Absatz.

Einem Codeblock oder einer Liste sollte eine Leerzeile vorausgehen und folgen. Dies ist für die HTML-Ausgabe nicht notwendig, hilft aber bei der ri-Ausgabe.

Methodennamen

Für einen Methodennamen im Text

Für eine Methode in der aktuellen Klasse oder dem aktuellen Modul verwenden Sie einen Doppelpunkt für eine Singleton-Methode oder ein Rautezeichen für eine Instanzmethode: ::bar, baz.
Andernfalls geben Sie den Klassennamen oder Modulnamen an und verwenden Sie einen Punkt für eine Singleton-Methode oder ein Rautezeichen für eine Instanzmethode: Foo.bar, Foo#baz.

Eingebetteter Code und Befehle

Code oder Befehle, die in laufenden Text eingebettet sind (d. h. nicht in einem Codeblock), sollten als Monofont formatiert werden.

Code, der ein einfacher String ist, sollte die Anführungszeichen enthalten.

Auto-Verlinkung

Meistens wird der Name einer Klasse, eines Moduls oder einer Methode automatisch verlinkt.

- Float.
- Enumerable.
- File.new
- File#read.

wird gerendert als

Float.

Enumerable.

File.new

File#read.

Im Allgemeinen sollte die automatische Verlinkung von RDoc nicht unterdrückt werden. Zum Beispiel schreiben wir einfach nur Float (das automatisch verlinkt wird).

Returns a Float.

was als gerendert wird

Gibt einen Float zurück.

Unterdrücken Sie die automatische Verlinkung jedoch, wenn das betreffende Wort sich nicht auf eine Ruby-Entität bezieht (z. B. einige Verwendungen von Class oder English).

Class variables can be tricky.

wird gerendert als

Klassenvariablen können knifflig sein.

Unterdrücken Sie auch die automatische Verlinkung, wenn sich das betreffende Wort auf das aktuelle Dokument bezieht (z. B. Float in der Dokumentation der Klasse Float).

In diesem Fall können Sie in Erwägung ziehen, den Namen zu Monofont zu zwingen, was die automatische Verlinkung unterdrückt und auch betont, dass das Wort ein Klassenname ist.

A +Float+ object represents ....

wird gerendert als

Ein Float-Objekt repräsentiert ....

Bei nur sehr wenigen, sehr häufig diskutierten Klassen können Sie in Erwägung ziehen, den großgeschriebenen Klassennamen ganz zu vermeiden. Zum Beispiel könnten Sie bei einigen Erwähnungen von Arrays einfach das Kleinbuchstaben-Wort array verwenden.

Anstatt

For an empty Array, ....

was als gerendert wird

Für ein leeres Array, ....

könnten Sie schreiben

For an empty array, ....

was als gerendert wird

Für ein leeres Array, ....

Diese lockerere Verwendung vermeidet sowohl automatische Verlinkungen als auch störende Schriftänderungen und wird wahrscheinlich keine Verwirrung stiften.

Dieses Prinzip kann nützlich angewendet werden, insbesondere für

Ein Array.
Eine Ganzzahl.
Ein Hash.
Ein String.

Es sollte jedoch *nur* angewendet werden, wenn auf eine *Instanz* der Klasse Bezug genommen wird, und *niemals*, wenn auf die Klasse selbst Bezug genommen wird.

Explizite Links

Beim Schreiben eines expliziten Links beachten Sie folgende Richtlinien.

`rdoc-ref` Schema

Verwenden Sie das rdoc-ref-Schema für

Einen Link in der Kern-Dokumentation zu anderer Kern-Dokumentation.
Einen Link in der Kern-Dokumentation zu Dokumentation in einem Standardbibliothek-Paket.
Einen Link in einem Standardbibliothek-Paket zu anderer Dokumentation in demselben Standardbibliothek-Paket.

Siehe Abschnitt „rdoc-ref Schema“ in [links].

URL-basierter Link

Verwenden Sie einen vollständigen URL-basierten Link für

Einen Link in der Standardbibliothek-Dokumentation zur Dokumentation im Kern.
Einen Link in der Standardbibliothek-Dokumentation zu Dokumentation in einem anderen Standardbibliothek-Paket.

Dadurch wird sichergestellt, dass der Link auch dann gültig ist, wenn die Paketdokumentation unabhängig (getrennt von der Kerndokumentation) erstellt wird.

Der Link sollte zu einem Ziel in docs.ruby-lang.org/en/master/ führen.

Verwenden Sie auch einen vollständigen URL-basierten Link für einen Link zu einem externen Dokument.

Variablennamen

Der Name einer Variablen (wie in ihrer call-seq angegeben) sollte als Monofont markiert werden.

Verwenden Sie auch Monofont-Text für den Namen einer transienten Variablen (d. h. einer Variablen, die nur in der Diskussion definiert und verwendet wird, wie z. B. n).

HTML-Tags

Vermeiden Sie im Allgemeinen die Verwendung von HTML-Tags (auch in Formaten, in denen dies erlaubt ist), da ri (das Ruby Interactive Reference Tool) diese möglicherweise nicht richtig rendert.

Tabellen

Vermeiden Sie insbesondere das Erstellen von Tabellen mit HTML-Tags (<table> usw.).

Alternativen

Ein verbatim Textblock, der Leerzeichen und Satzzeichen zur Formatierung des Textes verwendet; beachten Sie, dass Textformatierung nicht berücksichtigt wird.
- Beispiel Quelle.
- Entsprechende Ausgabe.
(Nur im Markdown-Format): Eine Github Flavored Markdown (GFM) Tabelle, die spezielle Formatierung für den Text verwendet.
- Beispiel Quelle.
- Entsprechende Ausgabe.

Sprachen in Beispielen

Für Symbole und Strings in Dokumentationsbeispielen

Bevorzugen Sie Englisch in englischer Dokumentation: 'Hello'.
Bevorzugen Sie Japanisch in japanischer Dokumentation: 'こんにちは'.
Wenn eine zweite Sprache benötigt wird (z. B. Zeichen mit unterschiedlicher Byte-Größe), bevorzugen Sie Japanisch in englischer Dokumentation und Englisch in japanischer Dokumentation.
Verwenden Sie Beispiele in anderen Sprachen nur bei Bedarf: siehe String#capitalize.

Dokumentation von Klassen und Modulen

Die allgemeine Struktur der Klassen- oder Moduldokumentation sollte sein:

Zusammenfassung
Gängige Verwendungszwecke, mit Beispielen
„Was ist hier“-Übersicht (optional)

Zusammenfassung

Die Zusammenfassung ist eine kurze Beschreibung dessen, was die Klasse oder das Modul tut und warum der Leser sie verwenden möchte. Vermeiden Sie Details in der Zusammenfassung.

Gängige Verwendungszwecke

Zeigen Sie gängige Verwendungszwecke der Klasse oder des Moduls. Abhängig von der Klasse oder dem Modul kann dieser Abschnitt in Länge und Komplexität stark variieren.

„Was ist hier“-Übersicht

Die Dokumentation einer Klasse oder eines Moduls kann einen Abschnitt „Was ist hier“ enthalten.

Richtlinien

Der Abschnittstitel lautet What's Here.
Erwägen Sie, die Elternklasse und alle eingebundenen Module aufzulisten; erwägen Sie [Links] zu deren „Was ist hier“-Abschnitten, falls vorhanden.
Alle im linken Inhaltsverzeichnis genannten Methoden sollten aufgelistet werden (einschließlich aller von einer anderen Klasse übernommenen Methoden).
Attribute (die nicht im Inhaltsverzeichnis enthalten sind) können ebenfalls aufgelistet werden.
Zeigen Sie Methoden als Einträge in einer oder mehreren Aufzählungslisten an.
- Beginnen Sie jeden Eintrag mit dem Methodennamen, gefolgt von einem Doppelpunkt und einer kurzen Beschreibung.
- Wenn die Methode Aliase hat, erwähnen Sie diese in Klammern vor dem Doppelpunkt (und listen Sie die Aliase nicht separat auf).
- Überprüfen Sie die gerenderte Dokumentation, um festzustellen, ob RDoc die Methode erkannt und verlinkt hat; wenn nicht, fügen Sie manuell einen Link ein.
Wenn es zahlreiche Einträge gibt, erwägen Sie, sie mit Überschriften in Unterabschnitte zu gruppieren.
Wenn es mehr als ein paar solcher Unterabschnitte gibt, erwägen Sie, direkt unter dem Hauptabschnittstitel ein Inhaltsverzeichnis hinzuzufügen.

Dokumentation von Methoden

Allgemeine Struktur

Die allgemeine Struktur der Methodendokumentation sollte sein:

Aufrufsequenz (für in C geschriebene Methoden).
Zusammenfassung (kurze Beschreibung).
Kurze Beispiele (optional)
Details und Beispiele.
Argumentbeschreibung (falls erforderlich).
Grenzfälle und Ausnahmen.
Zugehörige Methoden (optional).

Aufrufsequenz (für in C geschriebene Methoden)

Für in Ruby geschriebene Methoden dokumentiert RDoc die Aufrufsequenz automatisch.

Für in C geschriebene Methoden kann RDoc nicht ermitteln, welche Argumente die Methode akzeptiert, daher müssen diese mit der RDoc-Direktive call-seq: dokumentiert werden.

Für eine Singleton-Methode verwenden Sie die Form

class_name.method_name(method_args) {|block_args| ... } -> return_type

Beispiel

*  call-seq:
*    Hash.new(default_value = nil) -> new_hash
*    Hash.new {|hash, key| ... } -> new_hash

Für eine Instanzmethode verwenden Sie die Form (ohne Präfix, genau wie RDoc für eine in Ruby geschriebene Methode)

method_name(method_args) {|block_args| ... } -> return_type

Zum Beispiel in Array, verwenden Sie

*  call-seq:
*    count -> integer
*    count(obj) -> integer
*    count {|element| ... } -> integer

*  call-seq:
*    <=> other -> -1, 0, 1, or nil

Für eine Methode im Binäroperatorstil (z. B. Array#&) geben Sie self in der call-seq an (nicht z. B. array oder receiver).

*  call-seq:
*    self & other_array -> new_array

Argumente

Wenn die Methode keine Argumente akzeptiert, lassen Sie die Klammern weg.
Wenn die Methode optionale Argumente akzeptiert
- Trennen Sie jeden Argumentnamen und seinen Standardwert mit einem = (Gleichheitszeichen mit umgebenden Leerzeichen).
- Wenn die Methode das gleiche Verhalten mit einem weggelassenen oder einem expliziten Argument hat, verwenden Sie eine call-seq mit optionalen Argumenten. Verwenden Sie zum Beispiel
```
*  call-seq:
*    respond_to?(symbol, include_all = false) -> true or false
```
- Wenn das Verhalten bei einem weggelassenen oder einem expliziten Argument unterschiedlich ist, verwenden Sie eine call-seq mit separaten Zeilen. Verwenden Sie zum Beispiel in Enumerable
```
*  call-seq:
*    max    -> element
*    max(n) -> array
```

Block

Wenn die Methode keinen Block akzeptiert, lassen Sie den Block weg.
Wenn die Methode einen Block akzeptiert, sollte die call-seq {|args| ... } enthalten, nicht {|args| block } oder {|args| code }.
Wenn die Methode einen Block akzeptiert, aber ein Enumerator zurückgibt, wenn der Block weggelassen wird, sollte die call-seq beide Formen anzeigen
```
*  call-seq:
*    array.select {|element| ... } -> new_array
*    array.select -> new_enumerator
```

Rückgabetypen

Wenn die Methode mehrere verschiedene Typen zurückgeben kann, trennen Sie die Typen mit „oder“ und bei Bedarf mit Kommas.
Wenn die Methode mehrere Typen zurückgeben kann, verwenden Sie object.
Wenn die Methode den Empfänger zurückgibt, verwenden Sie self.
Wenn die Methode ein Objekt derselben Klasse zurückgibt, stellen Sie new_ voran, nur wenn das Objekt nicht self ist; Beispiel: new_array.

Aliase

Lassen Sie Aliase aus der call-seq weg, es sei denn, der Alias ist eine Operator-Methode. Wenn Sie sowohl eine reguläre Methode als auch eine Operator-Methode in der call-seq auflisten, erklären Sie im Abschnitt Details und Beispiele, wann die Verwendung der regulären Methode und wann die Verwendung der Operator-Methode empfohlen wird.

Zusammenfassung

Als nächstes kommt die Zusammenfassung, die eine kurze Beschreibung dessen ist, was die Methode tut und warum Sie sie verwenden möchten. Idealerweise ist dies ein einzelner Satz, aber für komplexere Methoden kann er einen ganzen Absatz erfordern.

Für Array#count ist die Zusammenfassung

Gibt die Anzahl der angegebenen Elemente zurück.

Dies ist großartig, da es kurz und beschreibend ist. Vermeiden Sie es, zu viel in die Zusammenfassung aufzunehmen, konzentrieren Sie sich auf die wichtigsten Informationen zum Vorteil des Lesers.

Kurze Beispiele

Für eine Methode, deren Dokumentation langwierig ist, sollten Sie einen „kurzen“ Abschnitt hinzufügen, der Beispiele zeigt, die die Verwendungszwecke der Methode zusammenfassen.

Der Abschnitt kann einige Benutzerfragen beantworten (ohne dass diese lange Dokumentationen lesen müssen); siehe Array#[] und Array#[]=.

Details und Beispiele

Die meisten nicht-trivialen Methoden profitieren von Beispielen sowie Details, die über die in der Zusammenfassung gegebenen hinausgehen. Im Abschnitt Details und Beispiele können Sie dokumentieren, wie die Methode verschiedene Arten von Argumenten behandelt, und Beispiele für die richtige Verwendung geben. In diesem Abschnitt konzentrieren Sie sich darauf, wie die Methode richtig verwendet wird, nicht darauf, wie die Methode mit falschen Argumenten oder Grenzfälle umgeht.

Nicht jedes Verhalten einer Methode erfordert ein Beispiel. Wenn die Methode dokumentiert ist, dass sie self zurückgibt, müssen Sie kein Beispiel liefern, das zeigt, dass der Rückgabewert derselbe ist wie der Empfänger. Wenn die Methode dokumentiert ist, dass sie nil zurückgibt, müssen Sie kein Beispiel liefern, das zeigt, dass sie nil zurückgibt. Wenn in den Details erwähnt wird, dass für einen bestimmten Argumenttyp ein leeres Array zurückgegeben wird, müssen Sie dafür kein Beispiel liefern.

Fügen Sie nur dann ein Beispiel hinzu, wenn es dem Benutzer zusätzliche Informationen liefert. Fügen Sie kein Beispiel hinzu, wenn es dieselben Informationen liefert, die in der Zusammenfassung oder den Details angegeben sind. Der Zweck von Beispielen ist es nicht, die in den Details gemachten Aussagen zu beweisen.

Viele Methoden, die ein optionales Block akzeptieren, rufen den Block auf, wenn er gegeben ist, geben aber einen neuen Enumerator zurück, wenn der Block nicht gegeben ist; in diesem Fall liefern Sie kein Beispiel, aber erwähnen Sie die Tatsache (mit dem automatisch verlinkten großgeschriebenen Enumerator).

*  With no block given, returns a new Enumerator.

Argumentbeschreibung (falls erforderlich)

Für Methoden, die Argumente erfordern, und wenn dies nicht offensichtlich und nicht explizit in den Details erwähnt oder implizit in den Beispielen gezeigt wird, können Sie Details zu den unterstützten Argumenttypen angeben. Bei der Diskussion von Argumenttypen verwenden Sie einfache Sprache, auch wenn sie weniger präzise ist, z. B. „level muss eine Ganzzahl sein“ und nicht „level muss ein Integer-konvertierbares Objekt sein“. Die überwiegende Mehrheit der Verwendung wird mit dem erwarteten Typ erfolgen, nicht mit einem Argument, das explizit in den erwarteten Typ konvertiert werden kann, und die Dokumentation des Unterschieds ist nicht wichtig.

Für Methoden, die Blöcke akzeptieren, kann es nützlich sein, den Typ des übergebenen Arguments zu dokumentieren, wenn dieser nicht offensichtlich ist, nicht explizit in den Details erwähnt und nicht implizit in den Beispielen gezeigt wird.

Wenn es mehr als ein Argument oder Blockargument gibt, verwenden Sie eine beschriftete Liste.

Grenzfälle und Ausnahmen

Erwähnen Sie für Grenzfälle von Methoden, wie z. B. unübliche Verwendung, kurz das Verhalten, aber liefern Sie keine Beispiele.

Dokumentieren Sie nur Ausnahmen, die ausgelöst werden, wenn sie nicht offensichtlich sind. Wenn Sie beispielsweise zuvor angegeben haben, dass ein Argumenttyp eine Ganzzahl sein muss, müssen Sie nicht dokumentieren, dass ein TypeError ausgelöst wird, wenn eine Nicht-Ganzzahl übergeben wird. Geben Sie keine Beispiele für das Auslösen von Ausnahmen an, es sei denn, dies ist ein gängiger Fall, wie z. B. dass Hash#fetch einen KeyError auslöst.

In einigen Fällen ist es nützlich zu dokumentieren, welche Methoden mit der aktuellen Methode verwandt sind. Zum Beispiel könnte die Dokumentation für Hash#[] Hash#fetch als verwandte Methode erwähnen, und Hash#merge könnte Hash#merge! als verwandte Methode erwähnen.

Überlegen Sie, welche Methoden mit der aktuellen Methode verwandt sein könnten, und wenn Sie denken, dass der Leser davon profitieren würde, fügen Sie am Ende der Methodendokumentation eine Zeile hinzu, die mit „Related: “ beginnt (z. B. „Related: fetch.“).
Listen Sie nicht mehr als drei verwandte Methoden auf. Wenn Sie der Meinung sind, dass mehr als drei Methoden verwandt sind, listen Sie die drei auf, die Ihrer Meinung nach am wichtigsten sind.
Erwägen Sie das Hinzufügen von
- Eine Formulierung, die vorschlägt, wie sich die verwandte Methode zur aktuellen Methode verhält oder von ihr unterscheidet. Siehe ein Beispiel unter Time#getutc.
- Beispielcode, der die Ähnlichkeiten und Unterschiede veranschaulicht. Siehe Beispiele unter Time#ctime, Time#inspect, Time#to_s.

Methoden, die mehrere Argumenttypen akzeptieren

Bei Methoden, die mehrere Argumenttypen akzeptieren, kann es in einigen Fällen nützlich sein, die verschiedenen Argumenttypen separat zu dokumentieren. Am besten verwenden Sie für jeden zu besprechenden Fall einen separaten Absatz.