Guidelines zur Dokumentation

Aus FHEMWiki
Version vom 26. Januar 2016, 18:24 Uhr von Markusbloch (Diskussion | Beiträge) (Allgemeine Überarbeitung/Verbesserung)

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 (&auml; , &ouml; , ...) 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.