Guidelines zur Dokumentation

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.

Kurzbeschreibung des Moduls

Jedes Modul muss eine kurze & knappe Beschreibung enthalten, welche für die Modulübersicht in der Commandref verwendet wird. Dadurch soll der Nutzer bei dem Überblicken der Modulübersicht ein grobes Verständnis erhalten, wofür dieses Modul gedacht ist. Die Beschreibung wird mit dem POD-Marker =item summary eingeleitet. Die Beschreibung ist dabei auf der selben Zeile direkt hinter dem POD-Marker zu setzen.

Bspw:

 =item summary controls a dimmable switch via FS20

Um eine Beschreibung auf Deutsch bereitzustellen, muss der entsprechende Suffix für deutsche Sprache verwendet werden:

 =item summary_DE steuert einen Dimmer über FS20

Der Text, welcher nach summary bzw. summary_DE folgt wird bis zum Ende der Zeile in der Modulübersicht der Commandref direkt neben dem Modulnamen verwendet. Dabei ist jedoch eine Beschränkung auf 80 Zeichen gegeben, damit die Beschreibungen nicht zu ausführlich werden und die gesamte Modulübersicht dadurch unnötig in die Breite geht. Diese Begrenzung gilt nur für die reine Beschreibung und umfasst nicht den POD-Marker sowie Leerzeichen am Anfang und am Ende des Textes.

Die Kurzbeschreibung soll eine kurze und prägnante Formulierung sein. Für typische Gerätemodule sollte man hier beantworten, welche(s) Gerät(e) von welchem Hersteller über was für eine Verbindung gesteuert werden. Bei Hilfsmodulen/Befehlsmodulen sollte entsprechend beantwortet werden, was dieses Modul grob leistet/bereitstellt.

Mehrsprachige Dokumentation

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

 =begin html

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

 =end html

Deutsche Dokumentation wird gekennzeichnet durch

 =begin html_DE

 <a id="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.

id

Seit diesem Beitrag von Anfang 2021 sollte statt der alten Schreibweise <a name="modulname"></a> die modernere <a id="modulname"></a>-Schreibweise genutzt werden:

<a id="MQTT2_DEVICE">
<a id="MQTT2_DEVICE-define">
<a id="MQTT2_DEVICE-attr">
<a id="MQTT2_DEVICE-attr-setList">

Weiter ist es seit rev. 24714 möglich, addToAttrList() und addToDevAttrList() so aufzurufen, dass FHEMWEB die notwendigen Informationen hat, um die Attribute passend zu sortieren und entsprechende Hilfetexte anzuzeigen, und es können "Wildcards" genutzt werden (siehe dieses Thema).

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.