Die Programmiersprache Ruby

Blog| Forum| Wiki  

Seit dem 1.Juni 2009 bemüht sich das RubyWiki um eine deutschsprachige Referenz zu Ruby in der Version 1.9.1. Frühere Versionen von Ruby werden nicht dokumentiert, um Verwirrung vorzubeugen und außerdem eine Referenz für die Zukunft zu haben.

Inhaltsverzeichnis

Wie lege ich eine neue Referenzseite an?

In den Artikeln Referenz:Standard Klassen und Module (Core) und Referenz:Standard Bibliotheken (Stdlib) gibt es eine Liste der Referenzseiten. Klick dort einfach einen der roten Links an (wie beim Erstellen einer gewöhnlichen Seite auch) und schon kannst du mit dem Erstellen der Dokumentation beginnen. Sollte eine Klasse oder ein Modul ausgelassen worden sein, scheue nicht davor zurück, den Artikeln den fehlenden Eintrag hinzuzufügen, achte aber darauf, dass dieser Eintrag wirklich nicht vorher vorhanden war und auch wirklich auf Ruby 1.9 zutrifft. Jede Referenzseite muss mit dem Präfix Referenz: beginnen, auf das ohne Leerzeichen der Name des Eintrags folgt.

Wie ist ein Referenzartikel aufgebaut?

Die Referenzartikel sind logisch strukturiert und lehnen sich an RDoc an. Beginne einen Referenzartikel stets mit einer möglichst ausführlichen Beschreibung des Moduls oder der Klasse, sodass der Benutzer weiss, wofür er dies überhaupt gebrauchen kann. Halte dich ansonsten an dieses Schema:

Allgemeine Beschreibung der Klasse oder des Moduls. 

==Konstanten==
* KONSTANTE (wert, falls möglich): Kurze Beschreibung. 
* ...

==Klassenmethoden==

===klassenmethode1===
{{ReferenzClassMethod
|use=klassenmethode1( erstesArg [, optarg] ) ==> rückgabewert
|args=
* erstesArg: erstes Argument
* optarg(standardwert): Optionales Argument
|desc=Eine Beschreibung der Klassenmethode 
|return=Rückgabewert
|example=<source lang="Ruby">
# ein stück Ruby code als Beispiel
</source>
<source lang="Plain">
Output kann auch hinzugefügt werden. 
</source>
|}}

===klassenmethode2===
...

==Instanzmethoden==

===instanzmethode1===
(Genau wie Klassenmethoden dokumentieren)

Im Falle von Modulen schreibe anstatt von "Klassenmethoden" von "Modulmethoden".

Um Redundanzen bei der Formatierung zu vermeiden und ein einheitliches Aussehen zu garantieren, existieren die Vorlagen ReferenzClassMethod und ReferenzInstanceMethod.

Die Anwendungszeile

Die Zeile Anwendung der Methodenreferenz ist besonders. Sie stellt eine abstrakte Syntax da, mithilfe derer man direkt alle möglichen Aufrufe der Methode in der möglichen Reihenfolge der Argumente erkennen kann. Sie wird nach folgenden Regeln aufgestellt:

  • Grundaufbau: methodenname(...) ==> Rückgabewert
  • Die ... aus dem oberen Schema werden durch die Argumente der Methode ersetzt:
    methodenname( arg1 , arg2 ), wobei immer ein Abstand zwischen einem Argumente und dem trennenden Komma ist.
  • Optionale Argumente werden durch eckige Klammern [ und ] dargestellt; ein Komma wird ebenfalls in diese Klammern eingeschlossen, falls es erforderlich ist.
    methodenname( arg1 [, optarg ] ) ==> Rückgabewert
  • Ein Restargument wird, angelehnt an die tatsächliche Ruby-Syntax, mit einem Sternchen * davor gekennzeichnet:
    methodenname( arg1 [, optarg [, *viele_weitere_wenn_nötig ] ] )
  • Die Standardwerte von optionalen Argumente können, müssen aber nicht in der Definitionszeile aufgeführt werden, und zwar als [opt = wert]. Würde dies die Methodendefinition unnötig lang machen, lasse sie weg (die Standardwerte werden ja ohnehin unter Argumente aufgeführt).
  • Methoden, die Blöcke entgegennehmen, werden mit geschweiften Klammern mit Pünktchen darin gekennzeichnet. Blockargumente werden wie im Quelltext innerhalb von Balken | aufgeführt.
    methodenname(arg [, optarg [, *beliebig_viele ] ] ){|b1 [, b2 = 0]|...} ==> Rückgabewert
  • Gibt es mehrere völlig unterschiedliche Anwendungen einer Methode, darf die Anwendung auch mehrzeilig sein. Trenne die Zeilen per <br />.
  • Wenn eine Methode keine Argumente entgegennimmt, kannst du leere Klammern () am Ende weglassen.
    methodenname ==> Rückgabewert

Desweiteren...

  • ...schau dir die bisher bestehenden Referenzseiten an. Dort kann man sich ansehen, wie es am besten funktioniert.
  • Falls etwas in diesem Schema fehlt: Füge es hinzu. Diese Hilfeseite kann man wie jeden Artikel in diesem Wiki einfach bearbeiten.