Guidelines zur Dokumentation: Unterschied zwischen den Versionen

Version vom 26. Januar 2016, 18:24 Uhr

Die Dokumentation eines Moduls nennt sich "Commandref" (Kurzform engl.: command reference) und befindet sich am Ende des jeweiligen Modulcodes nach der Zeile mit 1;.

Sie beginnt mit dem POD-Marker =pod und endet mit =cut, auch wenn es HTML und kein POD ist.

Eingruppierung (Geräte-/Hilfs-/Befehlsmodul)

Mit einem der folgenden POD-Marker wird festgelegt, in welchem Bereich der commandref.html das Modul aufgenommen wird. Zur Unterscheidung der einzelnen Kategorien siehe auch: Beitrag

Modulart	POD-Marker	Beschreibung
Gerätemodul (Device)	`=item device`	Alle Module die dazu dienen physikalische Hardware zu steuern oder Daten von physikalischen Devices zu sammeln. Hierunter fallen dabei auch Module, welche aus dem Internet Daten zur Verfügung stellen (z.B. WEATHER) die einer Art "Sensordaten" ähneln). Bspw: CUL, CUL_HM, FS20, ...
Hilfsmodul (Helper)	`=item helper`	Module, welche Events (oder andere Daten) von anderen Definitionen verarbeiten um ihre eigentliche Aufgabe zu erfüllen. Solche Module funktionieren nicht eigenständig, sondern nur durch die Parametrisierung mit existierenden Definitionsnamen um ihren Zweck zu erfüllen. Dazu gehören auch Module, die gewisse Steuerungsmechanismen dem User abnehmen oder andere Intelligenzen (z.B. zeitbasierte Module wie at oder WeekdayTimer). Bspw: at, notify, FileLog, watchdog, THRESHOLD, ...
Befehlsmodul (Command)	`=item command`	Module, welche einen FHEM-Systembefehl zur Verfügung stellen. Bspw: apptime, version, help, update, ...

Fehlt der item-Marker wird ein Modul standardmäßig als Gerätemodul eingruppiert.

Mehrsprachige Dokumentation

Englische Dokumentation, welches der Mindestbestandteil für offizielle FHEM-Module ist, wird gekennzeichnet durch:

 =begin html

 <a name="modulname"></a>
 blabla

 =end html

Deutsche Dokumentation wird gekennzeichnet durch

 =begin html_DE

 <a name="modulname"></a>
 blabla

 =end html_DE

Die Leerzeile nach dem Tag =begin html bzw. =begin html_DE ist Pflicht. Weitere Hinweise zur Dokumentation finden sich in diesem Beitrag

In der Dokumentation nach Möglichkeit nur Text und keine aufwendigen Formatierungen, Farben, Tabellen oder ähnliches verwenden (Thema). Tabellen-Tags welche mit Attributen versehen sind, werden nicht akzeptiert. Es geht hierbei nicht darum die Informationen möglichst schön zu formatieren sondern darum, die wichtigen Kerninformationen kurz und prägnant zu vermitteln. Für weiterführende Erklärungen dient dieses Wiki.

Syntaxprüfung

Zum Erzeugen von docs/commandref.html muss man im fhem Verzeichnis contrib/commandref_join.pl aufrufen, ohne Argumente (auf Startverzeichnis achten!). Damit wird die Commandref in allen aktuell genutzten Sprachen erstellt.

developer@machine:~/source/fhem/trunk/fhem> perl ./contrib/commandref_join.pl

Anschließend sollte man sich die generierte Commandref im Browser anschauen und prüfen, ob alles korrekt dargestellt wird. Insbesondere Umlaute der deutschen Sprache, welche nicht als HTML-Entität (ä , ö , ...) geschrieben sind, fallen hier gerne auf.

Desweiteren gibt es die Möglichkeit die Commandref eines einzelnen Moduls auf Syntax zu prüfen. Dazu das Skript commandref_join.pl mit der entsprechenden Modul-Datei aufrufen um eine solche Syntaxprüfung durchzuführen:

developer@machine:~/source/fhem/trunk/fhem> perl ./contrib/commandref_join.pl ./FHEM/98_version.pm

Sollte es grobe Fehler in der Commandref des übergebenen Moduls geben, so werden diese auf der Konsole ausgegeben.

@@ Zeile 1: / Zeile 1: @@
-Die Dokumentation eines Moduls befindet sich am Ende des jeweiligen Modulcodes nach der Zeile mit <code>1;</code>.
+Die Dokumentation eines Moduls nennt sich "Commandref" (Kurzform engl.: command reference) und befindet sich am Ende des jeweiligen Modulcodes nach der Zeile mit <code>1;</code>.
-Sie beginnt mit dem Tag <code>=pod</code>, auch wenn es html und kein pod ist.
+Sie beginnt mit dem POD-Marker <code>=pod</code> und endet mit <code>=cut</code>, auch wenn es HTML und kein POD ist.
-Mit dem Tag in der folgenden Zeile wird festgelegt, in welchem Bereich der commandref.html das Modul aufgenommen wird:
+== Eingruppierung (Geräte-/Hilfs-/Befehlsmodul) ==
-* <code>=item helper</code> = Helper
+Mit einem der folgenden POD-Marker wird festgelegt, in welchem Bereich der commandref.html das Modul aufgenommen wird. Zur Unterscheidung der einzelnen Kategorien siehe auch: {{Link2Forum|Topic=47155|Message=392865}}
-* <code>=item command</code> = Command
-* <code>=item device</code> = Device
-Fehlt das Tag wird standardmäßig Device genommen. Zur Unterscheidung von Helper/Device siehe: {{Link2Forum|Topic=47155|Message=392865}}
-Englische Dokumentation, die Mindestbestandteil für offizielle FHEM-Module ist, wird gekennzeichnet durch
+{| class="wikitable"
+|-
+!  style="min-width: 200px;" | Modulart !! style="text-align: center;min-width: 125px;" |POD-Marker             !! Beschreibung
+|-
+| Gerätemodul (Device)|| style="text-align: center;" |<code>=item device</code>  || Alle Module die dazu dienen physikalische Hardware zu steuern oder Daten von physikalischen Devices zu sammeln. Hierunter fallen dabei auch Module, welche aus dem Internet Daten zur Verfügung stellen (z.B. WEATHER) die einer Art "Sensordaten" ähneln).
+Bspw: CUL, CUL_HM, FS20, ...
+|-
+| Hilfsmodul (Helper)|| style="text-align: center;" | <code>=item helper</code>|| Module, welche Events (oder andere Daten) von anderen Definitionen verarbeiten um ihre eigentliche Aufgabe zu erfüllen. Solche Module funktionieren nicht eigenständig, sondern nur durch die Parametrisierung mit existierenden Definitionsnamen um ihren Zweck zu erfüllen. Dazu gehören auch Module, die gewisse Steuerungsmechanismen dem User abnehmen oder andere Intelligenzen (z.B. zeitbasierte Module wie at oder WeekdayTimer).
+Bspw: at, notify, FileLog, watchdog, THRESHOLD, ...
+|-
+| Befehlsmodul (Command)||style="text-align: center;" | <code>=item command</code>|| Module, welche einen FHEM-Systembefehl zur Verfügung stellen.
+Bspw: apptime, version, help, update, ...
+|}
+Fehlt der <code>item</code>-Marker wird ein Modul standardmäßig als Gerätemodul eingruppiert.
+== Mehrsprachige Dokumentation ==
+Englische Dokumentation, welches der Mindestbestandteil für offizielle FHEM-Module ist, wird gekennzeichnet durch:
 <pre>
   =begin html
@@ Zeile 27: / Zeile 44: @@
   =end html_DE
 </pre>
-Die Leerzeile nach dem Tag <code>begin html</code> bzw. <code>begin html_DE</code> ist Pflicht. Weitere Hinweise zur Dokumentation finden sich in diesem {{Link2Forum|Topic=18962|Message=392468}}
+Die Leerzeile nach dem Tag <code>=begin html</code> bzw. <code>=begin html_DE</code> ist Pflicht. Weitere Hinweise zur Dokumentation finden sich in diesem {{Link2Forum|Topic=18962|Message=392468}}
+In der Dokumentation nach Möglichkeit nur Text und keine aufwendigen Formatierungen, Farben, Tabellen oder ähnliches verwenden ({{Link2Forum|Topic=46371}}). Tabellen-Tags welche mit Attributen versehen sind, werden nicht akzeptiert. Es geht hierbei nicht darum die Informationen möglichst schön zu formatieren sondern darum, die wichtigen Kerninformationen kurz und prägnant zu vermitteln. Für weiterführende Erklärungen dient dieses Wiki.
+== Syntaxprüfung ==
+Zum Erzeugen von docs/commandref.html muss man im fhem Verzeichnis contrib/commandref_join.pl aufrufen, ohne Argumente (auf Startverzeichnis achten!). Damit wird die Commandref in allen aktuell genutzten Sprachen erstellt.
+<code>developer@machine:~/source/fhem/trunk/fhem&gt; perl ./contrib/commandref_join.pl</code>
-In der Dokumentation nach Möglichkeit nur Text und keine aufwendigen Formatierungen, Farben, Tabellen oder ähnliches verwenden ({{Link2Forum|Topic=46371}}).
+Anschließend sollte man sich die generierte Commandref im Browser anschauen und prüfen, ob alles korrekt dargestellt wird. Insbesondere Umlaute der deutschen Sprache, welche nicht als HTML-Entität (&amp;auml; , &amp;ouml; , ...) geschrieben sind, fallen hier gerne auf.
-Zum Erzeugen von docs/commandref.html muss man im fhem Verzeichnis contrib/commandref_join.pl aufrufen, ohne Argumente, das braucht jeder um die Doku zu testen (auf Startverzeichnis achten!):
+Desweiteren gibt es die Möglichkeit die Commandref eines einzelnen Moduls auf Syntax zu prüfen. Dazu das Skript commandref_join.pl mit der entsprechenden Modul-Datei aufrufen um eine solche Syntaxprüfung durchzuführen:
-<code>developer@machine:~/source/fhem/trunk/fhem&gt; perl contrib/commandref_join.pl</code>
+<code>developer@machine:~/source/fhem/trunk/fhem&gt; perl ./contrib/commandref_join.pl ./FHEM/98_version.pm</code>
+Sollte es grobe Fehler in der Commandref des übergebenen Moduls geben, so werden diese auf der Konsole ausgegeben.
 [[Kategorie:Development]]