Perl Module dokumentieren

Vor ein paar Tagen sagte mir mein FHEM System "... FHEM/99_myUtils.pm: No document text found". Mich hat diese Meldung erstmal verwirrt, sah mir nach einem Fehler aus.

Hintergrund: Die Entwickler haben die Erzeugung der commandref, einer der wichtigsten und besten Dokumentationen von FHEM, auf die lokale Installation verlagert. Der Vorteil: Es wird beim Update weniger heruntergeladen und die Doku wird aus den lokalen Modulen erzeugt. Damit bekommt die Datei mit den eigenen Routinen, die Chance in die Offline-Dokumentation einzugehen.

Wahrscheinlich hat bisher kaum jemand seine Dokumentation für die eigenen Routinen aufgeschrieben, allenfalls Kommentarzeilen direkt im Code.
Ich habe mich schlau gemacht und will daher mal zeigen wie das geht. Irgendwo stand im Forum sinngemäß: "Ein Module ohne Dokumentation ist wertlos" :-)

Ich habe die vorhanden Module durchsucht, habe im Internet recherchiert und als Ergebnis gibt es gleich zu Beginn eine Art Grundbaustein:

=pod
=begin html
... hier steht die Doku in englisch
=end html
=begin html_DE
... hier steht die Doku in deutsch
=end html_DE
=cut

In den meisten Modulen habe ich diesen Doku Abschnitt einfach am Ende des Perl Modules gefunden, also nach der Zeile mit dem Inhalt 1;
Laut diesem Beitrag ist es aber egal, wo man diesen Abschnitt einfügt. Das allerwichtigste ist die "Klammer", die den Abschnitt für Plain Old Documentation darstellt.

=pod
...
=cut

Dazwischen gibt es Schlüsselwörter und Text. Im Falle FHEM gibt es dann zwei "Klammern" eine für englische Doku eine für Deutsche. Wenn die deutsche Klammer fehlt, wird in der commandref ein Link und ein Standardtext erstellt.

=begin html
...
=end html

FHEM erfordert innerhalb des hmtl Abschnittes dann mindestens zwei Tags:

<a name="myUtils"></a>
<h3>myUtils</h3>

Der <a> Tag stellt einen Verweis dar, der <h3> Tag kennzeichnet die Überschrift. Beide Tags müssen sein, ansonsten kann FHEM die Doku nicht in die commandref einbinden. Der Abschnitt für die deutsche Doku kann komplett fehlen. Das folgende Minimum erzeugt einen Link und eine Überschrift in der commandref.

=pod
=begin html

<a name="myUtils"></a>
<h3>myUtils</h3>

=end html

=cut

Die Beschreibungen der einzelnen Routinen werden mit <ul> Tags geklammert und eventuell mit <ul> Tags weiter untergliedert. Dabei entsteht ein eingerückter Text. Beispiele können mit dem <code> Tag formatiert werden.
So schaut es als Gerüst aus:

=pod
=begin html

<a name="myUtils"></a>
<h3>myUtils</h3>
<ul>
  <b>Name</b>
  <br>
  Text<br>
  Examples:
  <ul>
   <code>Example Code </code><br>
  </ul>
</ul>

=end html
=cut

Mit diesem Befehl in der FHEM Kommando Zeile:

{system("/usr/bin/perl ./contrib/commandref_join.pl")}
{qx(/usr/bin/perl ./contrib/commandref_modular.pl)}

Kann die Erstellung der commandref im laufenden Betrieb getestet werden. Allerdings erfolgt die Ausgabe von Fehlern im Logfile von FHEM. Will man die Ausgabe direkt sehen, kann man im Terminalfenster folgendes eingeben:

cd /opt/fhem
sudo /usr/bin/perl ./contrib/commandref_join.pl

Wenn man anschließend die Ansicht testet, darf man den Browsercache nicht vergessen (F5).