Guidelines zur Dokumentation: Unterschied zwischen den Versionen

Version vom 25. Januar 2016, 22:53 Uhr

Die Dokumentation eines Moduls befindet sich am Ende des jeweiligen Modulcodes nach der Zeile mit 1;.

Sie beginnt mit dem Tag =pod, 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:

=item helper = Helper
=item command = Command
=item device = Device

Fehlt das Tag wird standardmäßig Device genommen. Zur Unterscheidung von Helper/Device siehe: Beitrag

Englische Dokumentation, die 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).

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!):

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

@@ Zeile 1: / Zeile 1: @@
-Die Dokumentation eines Moduls befindet sich am Ende des jeweiligen Moduls,
+Die Dokumentation eines Moduls befindet sich am Ende des jeweiligen Modulcodes nach der Zeile mit <code>1;</code>.
-nach dem 1;, und faengt mit =pod an, auch wenn es html und kein pod
-ist. Der Rest befindet sich in docs/commandref_frame.html.
-Englische Dokumentation wird gekennzeichnet durch
+Sie beginnt mit dem Tag <code>=pod</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:
+* <code>=item helper</code> = Helper
+* <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
+<pre>
   =begin html
   <a name="modulname"></a>
   blabla
   =end html
+</pre>
 Deutsche Dokumentation wird gekennzeichnet durch
+<pre>
   =begin html_DE
   <a name="modulname"></a>
   blabla
   =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}}
+In der Dokumentation nach Möglichkeit nur Text und keine aufwendigen Formatierungen, Farben, Tabellen oder ähnliches verwenden ({{Link2Forum|Topic=46371}}).
-Zum Erzeugen von docs/commandref.html muss man im fhem Verzeichnis
+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!):
-contrib/commandref_join.pl aufrufen, ohne Argumente, das braucht jeder
-um die Doku zu testen (auf Startverzeichnis achten!):
-developer@machine:~/source/fhem/trunk/fhem&gt; perl contrib/commandref_join.pl
+<code>developer@machine:~/source/fhem/trunk/fhem&gt; perl contrib/commandref_join.pl</code>
-Falls jemand ein neues Command oder einen Helper baut, dann muss der
-Hinweis in dem richtigen Index-Abschnitt in commandref_frame.html
-eingetragen werden, wenn nicht, dann wird angenommen, dass es ein
-Device ist.
-Bitte auf fehlende &lt;/ul&gt; und &lt;/li&gt; achten.
 [[Kategorie:Development]]