Wikipedia:Lua/Seitenorganisation und Dokumentation

Diese Seite beschreibt die Struktur der mit einem Lua-Modul zusammenhängenden Wikitext-Seiten und die Gliederung der Dokumentation zu einem Lua-Modul.

Seitenorganisation

Mehrfache Wikitext-Seiten zu einem Modul (etwa für Vorlagen-Tests, Testergebnisse oder mehrsprachige Dokumentationen) sind innerhalb des Namensraums Modul: (828) nicht möglich.

• Es kann zu jedem Modul (oder Unter-Modul) nur genau eine Seite geben, deren Name auf /Doku endet. Nur diese kann Wikitext enthalten; alle anderen Seiten werden als Lua-Quellcode aufgefasst. Deshalb werden einheitlich alle Seiten mit Wikitext als Unterseiten von Wikipedia:Lua/Modul ausgelagert.
• Weiterhin steht die Vorlage {{LuaModuleDoc}} zur Verfügung, die auf allen betroffenen Wikitext-Seiten eingebunden werden kann. Sie sorgt für ein einheitliches Navigations-Schema. Außerdem stellt sie alle erforderlichen Verlinkungen bereit und kategorisiert automatisch.

Diskussionsseiten

Alle Diskussionen zu allen Unterseiten werden zentral an einer einzigen Stelle geführt. Zu diesem Zweck sollen alle anderen sichtbaren Seiten Weiterleitungen dorthin erhalten.

• Nur die zentrale Diskussionsseite wird ggf. von allen Beteiligten beobachtet.
• Was versehentlich über das normale Diskussionsseiten-Link auf einer der anderen beteiligten Seiten (Modul, Sprachversion, Unter-Modul, Testseite) angelegt und vermerkt wird, bleibt unbeachtet.
• Nur ein Archiv soll alle Diskussionen bündeln.

Struktur

Die folgenden Seiten stehen mit einem Mustermodul im Zusammenhang:

• Modul:Mustermodul

  Lua-Quelltext.

• Modul:Mustermodul/Doku

  Diese Seite wird nur (automatisch) eingebunden auf Modul:Mustermodul und enthält nur eine einzige Zeile:

  • {{LuaModuleDoc}}
• Wikipedia:Lua/Modul/Mustermodul

  Diese Seite zeigt die Informationen an, die für die Nutzung im Rahmen einer Vorlage wichtig sind; sonst keine. Sie enthält jedoch nur eine einzige Zeile:

  • {{LuaModuleDoc}}

  Dies ist die zentrale Anlaufseite und wird auch kategorisiert.

• Wikipedia:Lua/Modul/Mustermodul/de

  Wikitext (deutschsprachig) zur Dokumentation der äußeren Funktionalität (Vorlagenprogrammierung) und der inneren Struktur (Lua-Programmierung). Beispiel siehe unten.

  Vorangestellt wird:

  • {{LuaModuleDoc}}
• Wikipedia:Lua/Modul/Mustermodul/en

  Genau wie vor, jedoch englischsprachig.

• Wikipedia:Lua/Modul/Mustermodul/****

  Genau wie vor, jedoch in der Sprache ****.

  {{LuaModuleDoc|****}} wäre dann auf allen Seiten zum Modul zu benutzen.

• Modul Diskussion:Lua/Modul/Mustermodul
  • #WEITERLEITUNG [[WD:Lua/Modul/Mustermodul]]
• Wikipedia Diskussion:Lua/Modul/Mustermodul

  Zentrale Diskussionsseite für alle zu Mustermodul gehörenden Seiten.

  Vorangestellt wird:

  • {{LuaModuleDoc}}
• Wikipedia Diskussion:Lua/Modul/Mustermodul/de
  • #WEITERLEITUNG [[WD:Lua/Modul/Mustermodul]]
• Wikipedia Diskussion:Lua/Modul/Mustermodul/en
  • #WEITERLEITUNG [[WD:Lua/Modul/Mustermodul]]

Die Anzeige nur einer Dokumentation oberhalb der Quelltext-Wiedergabe auf der Darstellung von Modul:Mustermodul (wie es durch MediaWiki vorgezeichnet war) wäre lediglich bei sehr kurzen Modulen sinnvoll gewesen. Für die Vorlagenprogrammierer ist jedoch der Lua-Quelltext uninteressant, und bei langem Lua-Quelltext und längerer Dokumentation ist die Kombination auf einer Seite mit ständigem Scrollen nicht sinnvoll. Hinzu kommt, dass Mehrsprachigkeit und Unterseiten nicht unterstützt werden.

Unter-Module

Jedes Modul soll selbstständig einsetzbar sein; dies wird bereits durch den Namen nahegelegt.

Es kann erforderlich sein, nicht-selbstständige Unter-Module auszugliedern:

• Übersichtlichkeit bei sehr umfangreichem Code.
• Abspaltung von reinen Daten-Tabellen.
• Getrennte Entwicklung und Verbesserung komplexer Teilaufgaben mit der Möglichkeit unabhängiger Erprobung.
• Seitenschutz.
• Automatisierter Test.

Unter-Module sollen nicht selbst durch #invoke in Vorlagen eingebunden werden. Sie könnten jedoch durch mw.loadData() bzw. mw.loadJsonData() oder in seltenen Ausnahmefällen von eng befreundeten Modulen mit require() benutzt werden; in letzterem Fall wäre jedoch eine saubere Ausgliederung als Bibliotheks-Modul zur allgemeinen Verwendung anzustreben.

Ein typischer Fall wäre ein unit test mit dem Seitennamen /test – sicherlich von keinem anderen Modul nutzbar. Allerdings kehrt sich hier das Verhältnis um, weil das selbstständige Modul von seiner eigenen Unterseite aufgerufen würde; gleichwohl auf Anhieb verständlich zugeordnet.

Zur Diskussion sollte auf die zentrale Diskussionsseite weitergeleitet werden. Eine Dokumentation kann auch in die Dokumentationsseite des selbstständigen Moduls integriert werden.

Seitenschutz

Jedes produktiv im Projekt eingesetzte Modul sollte halbgeschützt gegen IP-Bearbeitung und mit move:sysop vollgeschützt werden. Bei einem Bibliotheksmodul geht die Zahl der Einbindungen schnell in die Zehntausende; Elementar-Aufgaben könnten später auch Hunderttausende von Artikeln betreffen. Verschiebungen und Weiterleitungen sind ohnehin nicht möglich.

Testseiten

Zu einem produktiven Modul ist eine Testseite in Wikisyntax erforderlich. Sie erlaubt einen routinemäßigen Schnelltest, ob das Modul noch prinzipiell in ordnungsgemäßem Zustand ist. Über die Seitenvorschau beim Bearbeiten des Modul-Quellcodes kann vor dem Speichern überprüft werden, ob es zu unbeabsichtigten Nebenwirkungen kam.

• Der Seitenname sollte von der zentralen Dokumentationsseite abgeleitet werden und als Unterseite /Test oder /test heißen.
• Beispiel: Wikipedia:Lua/Modul/TemplatePar/test

Daneben gibt es den unit test im Modul-Namensraum mit dem vom Modul abgeleiteten Seitennamen /test (oder /Test). Dieser unterstützt einen automatisierten Test und vergleicht eine Vielzahl von Parameterkombinationen mit den erwarteten Resultaten.

Die Vorlage {{LuaModuleDoc}} sollte auf den jeweiligen Wikitext-Seiten eingebunden sein. Sie liefert dort die Linkbox. Umgekehrt werden in der Linkbox alle zugehörigen Seiten mit einem Link auf eine Testseite versehen, sofern vorhanden. Bei mehreren Testseiten wird die zuerst gefundene Seite in der folgenden Liste verlinkt:

1. Wikipedia:Lua/Modul/Mustermodul/Test
2. Wikipedia:Lua/Modul/Mustermodul/test
3. Modul:Mustermodul/Test
4. Modul:Mustermodul/test

Testseiten in Wikitext werden in Kategorie:Wikipedia:Lua/Modul/Testseite einsortiert. Diskussionsseiten sind entsprechend weiterzuleiten.

Dokumentation

Jedes produktiv im Projekt eingesetzte Modul bedarf einer Dokumentation. Neben der aktuellen Verwendung zur Vorlagenprogrammierung ist auch die spätere Wartung zu bedenken.

Nachstehend wird die deutschsprachige Version dargestellt.

Mindestumfang

{{LuaModuleDoc}}

<onlyinclude>'''<code>Mustermodul</code>''' – Modul zu diesem und jenem Zweck.

{{Anker|Vorlage}} Funktionen für Vorlagen

• ; FunktionA

:    Wirkung

:    Parameter

• ; FunktionB

:    Wirkung

:    Parameter

• ; FunktionC

:    Wirkung

:    Parameter

</onlyinclude>

{{Anker|Lua}} Funktionen für Lua-Module

(entfällt, wenn nicht unterstützt)

Zugriffsmöglichkeiten

• ; FunktionX

:    Wirkung

:    Parameter

• ; FunktionY

:    Wirkung

:    Parameter

Verwendung

Wahlweise:

• Allgemeine Bibliothek.
• Unterstützung speziell dieser und jener Vorlagen usw.

Abhängigkeiten

Wahlweise:

• Keine.
• Module mit require usw.

Weitere Abschnitte sind möglich je nach individueller Konstellation; gern auch Doku interner Funktionen.

Siehe auch

Wenn es etwas gibt.

[[Kategorie:Wikipedia:Lua/Modul/Dokumentation|Mustermodul]]

Nur der grün unterlegte Bereich ist für Vorlagenprogrammierer sichtbar und relevant.

Vorlagenprogrammierer erhalten einen Auszug aus der ersten auffindbaren Sprachversion. Er wird über <onlyinclude> usw. ausgegliedert.

Kopiervorlage

{{LuaModuleDoc}}
<onlyinclude>'''<code></code>''' – Modul
== {{Anker|Vorlage}} Funktionen für Vorlagen ==
;
:
</onlyinclude>
== {{Anker|Lua}} Funktionen für Lua-Module ==
== Verwendung ==
== Abhängigkeiten ==
[[Kategorie:Wikipedia:Lua/Modul/Dokumentation|*#*#*#*#*]]

Format

Lua-Module können leicht mehrere Dutzend Funktionen enthalten. Sie müssen in ihren Zwecken übersichtlich dargestellt sein.

• Für viele Funktionen mit einem Einzeiler als Wirkungsbeschreibung und wenigen Parametern bietet sich die Definitionsliste an.
  • Beispiel: Wikipedia:Lua/Modul/URLutil
• Bei wenigen Funktionen mit umfangreichen Einzelbeschreibungen kann die Gliederung in Unterabschnitte angemessen sein.

Welche Form im Einzelfall passt, muss anhand der konkreten Umstände entschieden werden.

Mehrsprachigkeit

Es ist zu erwarten, dass wir eine Version eines Moduls aus einem anderen Wiki-Projekt importieren; namentlich aus der englischsprachigen Wikipedia. Dann wäre die zugehörige Dokumentation (soweit vorhanden) entsprechend aufzubereiten und einzugliedern; später auch eine deutschsprachige Version zu erstellen.

Genauso, wie wir importieren, sollten wir universelle Standardaufgaben auch weltweit allen Wikis zur Verfügung stellen; dementsprechend dann in englischer Sprache programmieren und dokumentieren.

Beispielseiten

Bei den folgenden Modulen ist die Struktur beispielhaft realisiert:

• Wikipedia:Lua/Modul/Hello
• Wikipedia:Lua/Modul/URLutil

Mindestkollektion

Für den einfachsten Fall (nur deutschsprachig, keine Testseite) ergeben sich folgende Seiten:

• Modul:MeinLua
  • Lua-Quelltext.
• Modul:MeinLua/Doku
  • Eine Zeile: {{LuaModuleDoc|de}}
• Modul Diskussion:MeinLua
  • Eine Zeile: #WEITERLEITUNG [[Wikipedia Diskussion:Lua/Modul/MeinLua]]
• Wikipedia:Lua/Modul/MeinLua
  • Eine Zeile: {{LuaModuleDoc|de}}
• Wikipedia:Lua/Modul/MeinLua/de
  • Eigentlicher Dokumentationstext.
• Wikipedia Diskussion:Lua/Modul/MeinLua
  • Eine Zeile als Diskussionsstart: {{LuaModuleDoc|de}}
• Wikipedia Diskussion:Lua/Modul/MeinLua/de
  • Eine Zeile: #WEITERLEITUNG [[Wikipedia Diskussion:Lua/Modul/MeinLua]]