RDoc für Ihre Rails-Anwendung generieren

Weil eine Rails-Anwendung aus einer Reihe von Ruby-Quelldateien besteht, können Sie Rubys RDoc-System nutzen, um eine HTML-Dokumentation aus speziell formatierten Kommentaren zu erzeugen, die Sie in Ihrem Code einbetten.

Sie können Kommentare zu Beginn einer Klassendatei und vor allen öffentlichen Instanzmethoden innerhalb der Klassendatei platzieren. Sie verarbeiten das diese Klassendefinitionen enthaltende Verzeichnis dann mit dem rdoc-Befehl, der alle Ruby-Quelldateien verarbeitet und eine vorzeigbare HTML-Dokumentation erzeugt.

Sie könnten zum Beispiel eine Kochbuch-Anwendung besitzen, die einen ChaptersController definiert. Sie können die ChaptersController-Datei mit Kommentaren versehen:

# Dieser Controller enthält die Geschäftslogik für die Kochbuch-Kapitel. Details finden

# Sie in der Dokumentation der einzelnen öffentlichen Instanzmethoden.



class ChaptersController < ApplicationController



  # Diese Methode erzeugt ein neues Chapter-Objekt basierend auf dem Inhalt von


  # <tt>params[:chapter]</tt>.

  # * Ist der Aufruf der +save+-Methode für dieses Objekt erfolgreich, erscheint

  #   eine Notiz und die Aktion +list+ wird aufgerufen.

  # * Schlägt +save+ fehl, wird stattdessen die Aktion +new+ aufgerufen.


  def create

    @chapter = Chapter.new(params[:chapter])

    if @chapter.save

      flash[:notice] = 'Kapitel wurde erfolgreich angelegt.'

      redirect_to :action => 'list'

    else

      render :action => 'new'

    end

  end

...

Die Kommentare bestehen aus einer oder mehreren aufeinanderfolgenden Zeilen, denen ein Hash-Symbol (#) vorangestellt ist. Die Zeilen bilden Blöcke eines beschreibenden Textes. Der erste Kommentarblock einer Datei sollte die Funktion der Klasse beschreiben und sollte Nutzungsbeispiele enthalten oder zeigen, wie die Klasse im Bezug auf den Rest der Anwendung eingesetzt wird.

Sobald Sie Kommentare in die Klassen eingefügt haben, verwenden Sie rake doc:app, um das RDoc-HTML für die Anwendung zu generieren. Aus dem Stamm der Kochbuch-Anwendung führen Sie den folgenden Befehl aus, der ein Verzeichnis namens doc/app erzeugt, in dem eine Reihe von HTML-Dateien stehen:

$ rake doc:app




$ ls -F doc/app/

classes/     files/               fr_file_index.html    index.html

created.rid  fr_class_index.html  fr_method_index.html  rdoc-style.css

Die Ergebnisse von RDoc können Sie sich ansehen, indem Sie mit Ihrem Browser zu doc/app/index.html wechseln.

Diskussion

<|XrefColor>Abbildung 2-4 zeigt das RDoc-HTML, das von der Beispielanwendung der Lösung generiert wurde. Der ChaptersController wurde aus dem Classes-Navigationsframe gewählt und wird im Hauptfenster des Frame-Sets dargestellt.

Die für die create-Methode gerenderte Dokumentation zeigt einige der vielen Wiki-artigen Formatierungsoptionen, die in RDoc-Kommentaren verwendet werden können. Ein Feature der Dokumentation ist die Verlinkung der HTML-Seiten. Zum Beispiel ist das Wort »Chapter« in der Beschreibung der create-Methode ein Hyperlink auf die Dokumentation der Chapter-Modellklassendefinition. Hier einige gängige Formatierungsoptionen:

# = Überschrift eins

#

# == Überschrift zwei

#

# === Überschrift drei

Das Folgende erzeugt Überschriften in verschiedenen Größen:

# * Eins

# * Zwei

# * Drei

Dieser Code erzeugt Aufzählungslisten:

# 1. Eins

# 2. Zwei

# 3. Drei

Das Folgende erzeugt eine geordnete Liste:

# Fixed with example code:

#   class WeblogController < ActionController::Base

#     def index

#       @posts = Post.find_all

#       breakpoint "Breaking out from the list"

#     end

#   end



 Abbildung 2-4



 Der für eine Rails-Anwendung generierte RDoc HTML-Code

Soll der Beispielcode mit einer Nichtproportionalschrift dargestellt werden, fügen Sie nach dem #-Zeichen zwei Leerzeichen ein.

Sie können auch eine Liste der Begriffe und Definitionen erzeugen:

# [Begriff] Dies ist die Definition eines Begriffs.

Dieser Kommentar erzeugt eine definitionsartige Paarung, bei der der »Begriff« durch den darauf folgenden Text definiert wird.

Innerhalb von Absätzen können Sie Text mit Unterstrichen kursiv darstellen (z.B. _kursiv_). Sie können Text auch fett darstellen, indem Sie die Wörter zwischen »Sternchen« (z.B. *fett*) stellen. Sie können Inline-Text festlegen, der in einer Nichtproportionalschrift ausgegeben wird, indem Sie die Wörter mit »+« umgeben (z.B. +Befehl+).

Standardmäßig ignoriert RDoc private Methoden. Sie können RDoc explizit anweisen, die Dokumentation für eine private Methode zu generieren, indem Sie den Modifikator :doc: zusammen mit der Funktionsdefinition angeben. Ein Beispiel:

private

  def eine_private_methode # :doc:

  end

In ähnlicher Weise können Sie Code aus der Dokumentation heraushalten, indem Sie den Modifikator :nodoc: verwenden.

Dieses Rezept stammt aus dem Rails Kochbuch, veröffentlicht beim O’Reilly Verlag