Guidelines zur Dokumentation - Versionsgeschichte

Ph1959de: Tippfehler korrigiert

2021-08-06T15:52:05Z

Tippfehler korrigiert

← Nächstältere Version		Version vom 6. August 2021, 17:52 Uhr
Zeile 73:		Zeile 73:
	<a id="MQTT2_DEVICE-attr">		<a id="MQTT2_DEVICE-attr">
	<a id="MQTT2_DEVICE-attr-setList">		<a id="MQTT2_DEVICE-attr-setList">
	Weiter ist es seit rev. 24714 möglich, <code>addToAttrList()</code> und <code>addToDevAttrList()</code> so aufzurufen, dass FHEMWEB die ~~notewndigen~~ Informationen hat, um die Attribute passend zu sortieren und entsprechende Hilfetexte anzuzeigen, und es können "Wildcards" genutzt werden, siehe dieses {{Link2Forum\|Topic=120779}}.		Weiter ist es seit rev. 24714 möglich, <code>addToAttrList()</code> und <code>addToDevAttrList()</code> 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 {{Link2Forum\|Topic=120779}}).

	== Syntaxprüfung ==		== 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.		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.

Beta-User: "id"-Syntax ergänzt

2021-07-12T13:09:01Z

"id"-Syntax ergänzt

← Nächstältere Version		Version vom 12. Juli 2021, 15:09 Uhr
Zeile 49:		Zeile 49:
	=begin html		=begin html

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

Zeile 58:		Zeile 58:
	=begin html_DE		=begin html_DE

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

Zeile 66:		Zeile 66:

	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.		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.

			== id ==
			Seit diesem {{Link2Forum\|Topic=118915\|Message=1135123}} von Anfang 2021 sollte statt der alten Schreibweise <code><a name="modulname"></a></code> die modernere <code><a id="modulname"></a></code>-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, <code>addToAttrList()</code> und <code>addToDevAttrList()</code> so aufzurufen, dass FHEMWEB die notewndigen Informationen hat, um die Attribute passend zu sortieren und entsprechende Hilfetexte anzuzeigen, und es können "Wildcards" genutzt werden, siehe dieses {{Link2Forum\|Topic=120779}}.

	== Syntaxprüfung ==		== Syntaxprüfung ==

Markusbloch: /* Kurzbeschreibung des Moduls */

2016-08-20T20:04:09Z

Kurzbeschreibung des Moduls

← Nächstältere Version		Version vom 20. August 2016, 22:04 Uhr
Zeile 42:		Zeile 42:
	Der Text, welcher nach <code>summary</code> bzw. <code>summary_DE</code> 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.		Der Text, welcher nach <code>summary</code> bzw. <code>summary_DE</code> 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.		'''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 ==		== Mehrsprachige Dokumentation ==

Markusbloch: Hinzufügen von Modul-Kurzbeschreibung via =item summary

2016-08-20T19:59:36Z

Hinzufügen von Modul-Kurzbeschreibung via =item summary

← Nächstältere Version		Version vom 20. August 2016, 21:59 Uhr
Zeile 24:		Zeile 24:

	Fehlt der <code>item</code>-Marker wird ein Modul standardmäßig als Gerätemodul eingruppiert.		Fehlt der <code>item</code>-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 <code>=item summary</code> eingeleitet. Die Beschreibung ist dabei auf der selben Zeile direkt hinter dem POD-Marker zu setzen.

			Bspw:
			<pre>
			=item summary controls a dimmable switch via FS20
			</pre>

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

			<pre>
			=item summary_DE steuert einen Dimmer über FS20
			</pre>

			Der Text, welcher nach <code>summary</code> bzw. <code>summary_DE</code> 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 ==		== Mehrsprachige Dokumentation ==

Markusbloch: Allgemeine Überarbeitung/Verbesserung

2016-01-26T17:24:25Z

Allgemeine Überarbeitung/Verbesserung

← Nächstältere Version		Version vom 26. Januar 2016, 19:24 Uhr
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>		<pre>
	=begin html		=begin html
Zeile 27:		Zeile 44:
	=end html_DE		=end html_DE
	</pre>		</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> 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 (&auml; , &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> perl contrib/commandref_join.pl</code>		<code>developer@machine:~/source/fhem/trunk/fhem> 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]]		[[Kategorie:Development]]

Krikan: Aktualisierung

2016-01-25T20:53:11Z

Aktualisierung

← Nächstältere Version		Version vom 25. Januar 2016, 22:53 Uhr
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		=begin html

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

	=end html		=end html
			</pre>
	Deutsche Dokumentation wird gekennzeichnet durch		Deutsche Dokumentation wird gekennzeichnet durch
			<pre>
	=begin html_DE		=begin html_DE

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

	=end html_DE		=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> perl contrib/commandref_join.pl		<code>developer@machine:~/source/fhem/trunk/fhem> 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 </ul> und </li> achten.~~

	[[Kategorie:Development]]		[[Kategorie:Development]]

Krikan: veralteten Text entfernt

2015-04-20T17:35:16Z

veralteten Text entfernt

← Nächstältere Version		Version vom 20. April 2015, 19:35 Uhr
Zeile 20:		Zeile 20:

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


	~~Die Dokumentation einiger Module aus contrib wird nicht mehr ins~~
	~~commandref.html geschrieben (HOL, DbLog, dumpdef,~~
	~~FHEMRENDERER), da docs/commandref.html erstellt wird, indem docs/~~
	~~commandref_frame.html mit der Doku in den fhem/NN_*.pm Dateien~~
	~~ergaenzt wird.~~

	Falls jemand ein neues Command oder einen Helper baut, dann muss der		Falls jemand ein neues Command oder einen Helper baut, dann muss der

Krikan: Kategorie Guideline gelöscht

2014-08-29T08:03:04Z

Kategorie Guideline gelöscht

← Nächstältere Version		Version vom 29. August 2014, 10:03 Uhr
Zeile 35:		Zeile 35:
	Bitte auf fehlende </ul> und </li> achten.		Bitte auf fehlende </ul> und </li> achten.

	[[Kategorie:Development~~]][[Kategorie:Guidelines~~]]		[[Kategorie:Development]]

Pahenning am 30. Januar 2014 um 07:49 Uhr

2014-01-30T07:49:07Z

← Nächstältere Version		Version vom 30. Januar 2014, 09:49 Uhr
Zeile 35:		Zeile 35:
	Bitte auf fehlende </ul> und </li> achten.		Bitte auf fehlende </ul> und </li> achten.

	[[Kategorie:Development]]		[[Kategorie:Development]][[Kategorie:Guidelines]]

Pahenning: Pahenning verschob Seite DocumentationGuidelines nach Guidelines zur Dokumentation: Systematische Verbesserung des Wiki

2014-01-30T07:48:36Z

Pahenning verschob Seite DocumentationGuidelines nach Guidelines zur Dokumentation: Systematische Verbesserung des Wiki

← Nächstältere Version	Version vom 30. Januar 2014, 09:48 Uhr
(kein Unterschied)