Quelltext der Seite Simpsonspedia:Lua/Seitenorganisation und Dokumentation

{{Simpsonspedia:Lua/Linkbox}}
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 <code>Modul:</code> (828) nicht möglich.
* Es kann zu jedem Modul (oder [[#Unter-Module|Unter-Modul]]) nur genau eine Seite geben, deren Name auf <code>/Doku</code> endet. Nur diese kann Wikitext enthalten; alle anderen Seiten werden als Lua-Quellcode aufgefasst. Deshalb werden einheitlich alle Seiten mit Wikitext als Unterseiten von [[Simpsonspedia:Lua/Modul]] ausgelagert.
* Weiterhin steht die Vorlage {{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:
* <code>Modul:</code>''Mustermodul''
*: Lua-Quelltext.
* <code>Modul:</code>''Mustermodul''<code>/Doku</code>
*: Diese Seite wird nur (automatisch) eingebunden auf <code>Modul:</code>''Mustermodul'' und enthält nur eine einzige Zeile:
** <code>{&#123;LuaModuleDoc}}</code>
* <code>Simpsonspedia:Lua/Modul/</code>''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:
** <code>{&#123;LuaModuleDoc}}</code>
*: Dies ist die zentrale Anlaufseite und wird auch kategorisiert.
* <code>Simpsonspedia:Lua/Modul/</code>''Mustermodul''<code>/de</code>
*: Wikitext (deutschsprachig) zur Dokumentation der äußeren Funktionalität (Vorlagenprogrammierung) und der inneren Struktur (Lua-Programmierung). Beispiel siehe [[#Dokumentation|unten]].
*: Vorangestellt wird:
** <code>{&#123;LuaModuleDoc}}</code>
* <code>Simpsonspedia:Lua/Modul/</code>''Mustermodul''<code>/en</code>
*: Genau wie vor, jedoch englischsprachig.
* <code>Simpsonspedia:Lua/Modul/</code>''Mustermodul''/****
*: Genau wie vor, jedoch in der Sprache ****.
*: <code>{&#123;LuaModuleDoc|****}}</code> wäre dann auf allen Seiten zum Modul zu benutzen.
* <code>Modul Diskussion:Lua/Modul/</code>''Mustermodul''
** <code>#WEITERLEITUNG [&#91;WD:Lua/Modul/''Mustermodul'']]</code>
* <code>Simpsonspedia Diskussion:Lua/Modul/</code>''Mustermodul''
*: Zentrale Diskussionsseite für alle zu ''Mustermodul'' gehörenden Seiten.
*: Vorangestellt wird:
** <code>{&#123;LuaModuleDoc}}</code>
* <code>Simpsonspedia Diskussion:Lua/Modul/</code>''Mustermodul''<code>/de</code>
** <code>#WEITERLEITUNG [&#91;WD:Lua/Modul/</code>''Mustermodul''<code>]]</code>
* <code>Simpsonspedia Diskussion:Lua/Modul/</code>''Mustermodul''<code>/en</code>
** <code>#WEITERLEITUNG [&#91;WD:Lua/Modul/</code>''Mustermodul''<code>]]</code>
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 <code>#invoke</code> in Vorlagen eingebunden werden. Sie könnten jedoch durch <code>mw.loadData()</code> bzw. <code>[[Hilfe:Lua/Daten#JSON|mw.loadJsonData()]]</code> oder in seltenen Ausnahmefällen von eng befreundeten Modulen mit <code>require()</code> benutzt werden; in letzterem Fall wäre jedoch eine saubere Ausgliederung als Bibliotheks-Modul zur allgemeinen Verwendung anzustreben.

Ein typischer Fall wäre ein ''[[Modultest|unit test]]'' mit dem Seitennamen <code>/test</code>&nbsp;– 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 [[Hilfe:Lua#redirect|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 <code>/Test</code> oder <code>/test</code> heißen.
* ''Beispiel:'' [[Simpsonspedia:Lua/Modul/TemplatePar/test]]

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

Die Vorlage {{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:
# <code>Simpsonspedia:Lua/Modul/</code>''Mustermodul''<code>/Test</code>
# <code>Simpsonspedia:Lua/Modul/</code>''Mustermodul''<code>/test</code>
# <code>Modul:</code>''Mustermodul''<code>/Test</code>
# <code>Modul:</code>''Mustermodul''<code>/test</code>

Testseiten in Wikitext werden in [[:Kategorie:Simpsonspedia: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 ===
<div style="border: solid 2px #0000FF; padding: 1em;">
<code>{&#123;LuaModuleDoc}}</code>
<div style="background-color: #B0FFB0;">
<code>&lt;onlyinclude></code><code>&apos;&apos;&apos;&lt;code></code>''Mustermodul''<code>&lt;/code>&apos;&apos;&apos;</code> – Modul zu diesem und jenem Zweck.
; <code>{&#123;Anker|Vorlage}}</code> Funktionen für Vorlagen
:* <code>;</code> FunktionA
:: <code>:</code> &nbsp;&nbsp; Wirkung
:: <code>:</code> &nbsp;&nbsp; Parameter
:* <code>;</code> FunktionB
:: <code>:</code> &nbsp;&nbsp; Wirkung
:: <code>:</code> &nbsp;&nbsp; Parameter
:* <code>;</code> FunktionC
:: <code>:</code> &nbsp;&nbsp; Wirkung
:: <code>:</code> &nbsp;&nbsp; Parameter
<code>&lt;/onlyinclude></code></div>
; <code>{&#123;Anker|Lua}}</code> Funktionen für Lua-Module
: ''(entfällt, wenn nicht unterstützt)''
: Zugriffsmöglichkeiten
:* <code>;</code> FunktionX
:: <code>:</code> &nbsp;&nbsp; Wirkung
:: <code>:</code> &nbsp;&nbsp; Parameter
:* <code>;</code> FunktionY
:: <code>:</code> &nbsp;&nbsp; Wirkung
:: <code>:</code> &nbsp;&nbsp; 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.''
[&#91;Kategorie:Simpsonspedia:Lua/Modul/Dokumentation|''Mustermodul'']]
</div>
''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 <code>&lt;onlyinclude></code> usw. ausgegliedert.

=== Kopiervorlage ===
 {&#123;LuaModuleDoc}}
 &lt;onlyinclude>&apos;&apos;&apos;&lt;code>&lt;/code>&apos;&apos;&apos; – Modul
 == {&#123;Anker|Vorlage}} Funktionen für Vorlagen ==
 ;
 :
 &lt;/onlyinclude>
 == {&#123;Anker|Lua}} Funktionen für Lua-Module ==
 == Verwendung ==
 == Abhängigkeiten ==
 [&#91;Kategorie:Simpsonspedia: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 [[Hilfe:Listen#dl|Definitionsliste]] an.
** ''Beispiel:'' [[Simpsonspedia: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.


== Beispielseiten ==
Bei den folgenden Modulen ist die Struktur beispielhaft realisiert:
* [[Simpsonspedia:Lua/Modul/Hello]]
* [[Simpsonspedia:Lua/Modul/URLutil]]

=== Mindestkollektion ===
Für den einfachsten Fall (nur deutschsprachig, keine Testseite) ergeben sich folgende Seiten:
* <code>Modul:</code>''MeinLua''
** Lua-Quelltext.
* <code>Modul:</code>''MeinLua''<code>/Doku</code>
** Eine Zeile: <code>{&#123;LuaModuleDoc|de}}</code>
* <code>Modul Diskussion:</code>''MeinLua''
** Eine Zeile: <code>#WEITERLEITUNG [&#91;Simpsonspedia Diskussion:Lua/Modul/</code>''MeinLua''<code>]]</code>
* <code>Simpsonspedia:Lua/Modul/</code>''MeinLua''
** Eine Zeile: <code>{&#123;LuaModuleDoc|de}}</code>
* <code>Simpsonspedia:Lua/Modul/</code>''MeinLua''<code>/de</code>
** Eigentlicher Dokumentationstext.
* <code>Simpsonspedia Diskussion:Lua/Modul/</code>''MeinLua''
** Eine Zeile als Diskussionsstart: <code>{&#123;LuaModuleDoc|de}}</code>
* <code>Simpsonspedia Diskussion:Lua/Modul/</code>''MeinLua''<code>/de</code>
** Eine Zeile: <code>#WEITERLEITUNG [&#91;Simpsonspedia Diskussion:Lua/Modul/</code>''MeinLua''<code>]]</code>
<noinclude>
[[Kategorie:Simpsonspedia:Lua|Seitenorganisation]]
</noinclude>