Dokumentations-Leitfaden

Aus Romwiki

Hier geht es um die Dokumentation von Funktionen und Events.

Ich möchte euch bitten, die derzeitige Struktur beizubehalten. Hierzu dieser kleine Leitfaden:

• Änderungen nur durch angemeldete Benutzer! Aber der Anmeldevorgang ist wirklich schmerzlos.
• Prüfen, ob die Funktion schon dokumentiert ist; die maßgebliche URL: Category:API Funktion

• Wenn ja, dann

• ggf. korrigieren oder erweitern.

• Wenn nicht, dann

• einen neuen Eintrag bauen, indem Ihr in der "Liste aller Funktionen" den Funktionsnamen in [[doppelte eckige Klammern]] packt und somit einen Link daraus baut. Die URL für die Liste: Liste aller Funktionen.
• Dem verlinkten Eintrag durch anklicken folgen, so entsteht die neue Seite. Dann dort editieren.

• Die Seite zur Funktion hat (normalerweise) jeweils 3 Header (mit ===, also 3 x =) namens "Aufruf", "Beschreibung", "Siehe auch". Optional noch "Hinweis", "Bemerkung" oder so, vor dem "Siehe auch".
• In "Aufruf" wird der Aufruf mit einem führenden Blank eingebaut, so kommt dieses hervorgehobene Fensterchen in Nichtproportionalschrift
• In "Beschreibung" bitte kurz sagen, wozu die Funktion gut ist. Am besten in einem einzigen Satz.
• Dann erst den/die Aufrufparameter (so vorhanden) dokumentieren, dann eine Leerzeile, dann den/die Rückgabewerte. Alle als Definitionliste, also in einer Zeile erst Semikolon ( ; ), Parameter-Name, Doppelpunkt ( : ), Definition.
• Dann natürlich gerne auch alles weitere Wissenswerte zur Funktion.
• Unter "Siehe auch" so möglich und sinnvoll Links auf verwandte Funktionen (auch wenn noch nicht fertig dokumentiert; die Namen sind ja schon mal bekannt!). Hier sollten auch die Kategorien stehen, zu der diese Seite gehört, z.B. bei den Funktionen
  [[:Category:API Funktion|API-Funktionen]] .

• Der Doppelpunkt am Anfang sagt, hier soll ein Link auf die Kategorie gebaut werden, nicht ein Eintrag in die Kategorie.
• Der senkrechte Strich ( | ) trennt den internen Kategorie-Namen von dem Text, der für Menschen an dieser Stelle ausgegeben werden soll.
• Mehrere "siehe auch"-Links kann man mit • trennen, das sind kleine Bullet-Punkte zwischen • den • Link items.

• Ganz unten dann: [[Category:API Funktion]] - so kommt dann dieser Beitrag in die alphabetische Zusammenfassung aus dem 1. Link.
• Fertig!

Klingt kompliziert, ist aber mit Beispiel gar nicht schwer. Diese Struktur erlaubt es mir später hoffentlich auch, mittels Transclusion die Einzelbeiträge zu einer Mega-Seite oder mehreren zusammenzufassen. Oder so.

Beispiel

    === Aufruf ===

    icon, name, itemCount, locked = GetGoodsItemInfo( id )

    === Beschreibung ===

    Einige wenige Informationen zu einem Item im Item-Cache des Spielers. Die Daten werden (u.a. ?) zum Aufbau des Buttons Rucksack verwendet, der einen Taschenplatz darstellt.

    ;id: anscheinend ein Index in den Item-Cache; z.B. <code>64</code>. Die Nummer passt zu dem von [[GetBagItemInfo]] zurückgegebenen Index.<br>Die Zahlen werden vom Client anscheinend willkürlich vergeben, man kann sich nicht darauf verlassen, dass in unterschiedlichen Spielsitzungen gleiche Indizes gleiche Items bedeuten!

    ;icon: Dateiname des Icons, z.B. <code>interface/icons/quest_stone12</code>
    ;name: z.B. <code>"Steinblock"</code>
    ;itemCount: die Anzahl identischer Items im Stapel in dem Taschenplatz, z.B. <code>7</code>
    ;locked: unbekannt, normalerweise <code>false</code>

    === Siehe auch ===

    [[:Category:API Funktion|API-Funktionen]]

    [[Category:API Funktion]]