Dokumentation update required

[martinp876]

ich beantrage, dass die Beschreibung insbesondere der Zerntralen Funktionen sauber und verständlich dokumentiert werden.
Zentrale Attribute sollten in einem Block zu finden sein, die Bedeutung dorteinheitlich und unmissvertändlich nachzulesen sein.
Mich ärgert es ständig, wenn ich etwas einauen will und jedes mal nicht 100% erkennen kann, wie das Kommando funktioniert. So schwer ist eine korrekte Doku nun auch wieder nicht. Ich will hier nicht den Code also Doku heranziehen müssen.

Nun Konkret:
gerade wollte ich für HMCCU (egal) STATE korrekt setzen (was hier eine kleine Kathastrophe ist). Also Attr stateFormat. Beschreibung gelesen:
Findet man ganz unten in readingFNAttributes - weiss man.

Modifies the STATE of the device, shown by the list command or in the room overview in FHEMWEB.

==> Modifies the internalVal STATE. Period.

If not set, its value is taken from the state reading.

==>Default is the reading "state". => könnte man bei einer Beschreinung von STATE unterbringen. U.a. gibt es hier unschöne Einschränkungen bei Notifies - das ist einen eigenen Absatz wert.

If set, then every word in the argument is replaced by the value of the reading if such a reading for the current device exists.

If set (eh klar)
Jedes Wort im Argument wird mit den Wert des Readings ersetzt, wenn so ein Reading existiert. Hä?
Also "stateFormat <readingName>" setzt internal STATE auf den Wert des Readings "readingName". Werden nun einzelne Worter des Attributs geparsed? Wird der Defautl gesetzt, wenn das Reading nicht existiert?
Ist das Kommando (ReadingsVal($NAME,<readingName>,ReadingsVal($NAME,"state",'undef'))?

If the value of this attribute is enclosed in {}, then it is evaluated.

Perfekt. Warum ist $NAME nicht zulässig?

statevals <text>:<text>[,...]
Define substitution for values of set commands. The parameters text are available as set commands.
Example:
attr my_switch statevals on:true,off:false
set my_switch on

Wir lese ich das ? Können wir die Worte sauber definieren.
values of set commands: Das sind also  nicht die Komamdos sondern die parameter (so werden sie glaube ich immer bezeichnet - nicht values). Wir reden also nicht von Kommandos sondern von den Parametern eines Kommandos.
Text wird also mit text ersetzt. herrlich. <set_text>:<exec_text> ist möglich?
set my_switch on  macht nun was? wird das eingegeben oder ausgeführt?

statevals <cmd_text>:<exec_text>[,...]
Define substitution for set-command parameter-string. In the parameter-string of each set command <cmd_text> will be sibstituted by <exec_text>.
set <entity> <cmd> <paramlist> (param list is the complete list of all parameter given
foreach (stateVals-pair){
  exec_param =~ s/cmd_text/exec_text/;
}
Replacement will be cumulativ. replacement order:  left side pair will be replaced first.

Example:
attr my_switch statevals on:true,off:false
set my_switch on
will issue the command
set my_switch true

Findet das Replacement nun statt nachdem der Parameter-string in parameter zerlegt wurde oder vorher? Wird die Schleife also einmal für ParameterString ausgeführt oder je Parameter?
Muss ich das nun im Code nachsehen? oder alles expermentell ermitteln?

[yoda_gh]

Hast Du Patches dazu?

[martinp876]

unklar.
ich will nicht die Doku für den Entwickler schreiben - insbesondere des Kernals. Auf Commandref level macht das doch der Entwickler.
Das sind 2 Beispiele - da müsste man einmal drüber schauen
Wichtiger - Ich könnte bestenfalls dokumentieren, wie es gerade geht. Bei Stateformat vermute ich, dass $NAME im {} expression funktionieren sollte und es nur ein Bug ist. Muss der Entwickler beurteilen und klarstellen.

[Otto123]

Wird der Defautl gesetzt, wenn das Reading nicht existiert?
...
Perfekt. Warum ist $NAME nicht zulässig?

wenn das reading nicht existiert wird nichts ersetzt - > Sonst werden alle Wörter im Wert des Attributes durch das entsprechende Reading des Gerätes ersetzt (soweit vorhanden).
...
weil es an der Stelle $name ist mMn deshalb weil es der Name des Gerätes selbst ist. Bei notify ist $NAME der Name des auslösenden Gerätes und nicht des Geräte selbst.

[zap]

Eigentlich dachte ich, dass die Doku von HMCCU ganz gut ist, aber die Beschreibung von statevals ist tatsächlich irreführend. Insofern danke für den Hinweis, v.a. auch deshalb, weil statevals ab Version 4.4 eigentlich nur noch aus Kompatibilitätsgründen existiert und nur noch eine untergeordnete Rolle spielt.
Ich passe die Beschreibung an.

[rudolfkoenig]

ich beantrage, dass die Beschreibung insbesondere der Zerntralen Funktionen sauber und verständlich dokumentiert werden.

Da diese Anforderung subjektiv ist, kann ich es nicht objektiv erfuellen.

Ich kann aber zusagen, dass ich die in fhem.pl verarbeiteten Attribute, die hier angebotenen Funktionen, bzw. die aus fhem.pl angesprochenen Funktionen beschreibe. Ich setzte das auf meine Aufgabenliste.

[rudolfkoenig]

Ich habe damit angefangen, und habe schonmal die globalen Variablen dokumentiert in docs/fhem_api.txt.

Bin inzwischen nicht mehr der Ansicht, dass eine Dokumentation in dieser Form eine Gute Idee ist:
- alle Aenderungen muessen in der Doku nachgezogen werden, was dazu fuehren wird, dass Doku und Code nicht immer synchron sein werden.
- diese Doku erwaehnt nur kurz, wozu die Variablen da sind, im Form eines Manuals bzw. Command-Reference. Es wird nicht reichen, um damit sinnvolle Module zu schreiben, dafuer waeren (je nach Anspruch und Vorwissen) mehrere Buecher notwendig.

Ich finde es viel sinnvoller auf konkrete Fragen im Forum eine Beschreibung oder gar eine Code-Anpassung zu liefern.

Da ich aber zugesagt habe, werde ich dieses Dokument fertigstellen.