add a hook for reads to be done initially

inital reads from HW should be done in the thread started by
startModule, not in startModule itself.

- add a hook method 'initialReads' for this
+ add doc for init methods
+ fix some errors in doc

Change-Id: I914e3b7ee05050eea1ee8aff3461030adf08a461
Reviewed-on: https://forge.frm2.tum.de/review/c/secop/frappy/+/31374
Tested-by: Jenkins Automated Tests <pedersen+jenkins@frm2.tum.de>
Reviewed-by: Enrico Faulhaber <enrico.faulhaber@frm2.tum.de>
Reviewed-by: Markus Zolliker <markus.zolliker@psi.ch>

doc/source/magic.rst

@@ -8,7 +8,24 @@ what the framwork does for you.
 Startup
 .......
 
-TODO: describe startup: init methods, first polls
+On startup several methods are called. First :meth:`earlyInit` is called on all modules.
+Use this to initialize attributes independent of other modules, if you can not initialize
+as a class attribute, for example for mutable attributes.
+
+Then :meth:`initModule` is called for all modules.
+Use it to initialize things related to other modules, for example registering callbacks.
+
+After this, :meth:`startModule` is called with a callback function argument.
+:func:`frappy.modules.Module.startModule` starts the poller thread, calling
+:meth:`writeInitParams` for writing initial parameters to hardware, followed
+by :meth:`initialReads`. The latter is meant for reading values from hardware,
+which are not polled continuously. Then all parameters configured for poll are polled
+by calling the corresponding read_*() method. The end of this last initialisation
+step is indicated to the server by the callback function.
+After this, the poller thread starts regular polling, see next section.
+
+When overriding one of above methods, do not forget to super call.
+
 
 .. _polling:
 

doc/source/programming.rst

@@ -95,5 +95,23 @@ Example code:
             return self.read_target()  # return the read back value
 
 
+Parameter Initialisation
+------------------------
+
+Initial values of parameters might be given by several different sources:
+
+1) value argument of a Parameter declaration
+2) read from HW
+3) read from persistent data file
+4) value given in config file
+
+For (2) the programmer might decide for any parameter to poll it regularely from the
+hardware. In this case changes from an other input, for example a keyboard or other
+interface of the connected devices would be updated continuously in Frappy.
+If there is no such other input, or if the programmer decides that such other
+data sources are not to be considered, the hardware parameter might be read in just
+once on startup, :func:`frappy.modules.Module.initialReads` may be overriden.
+This method is called once on startup, before the regular polls start.
+
 
 .. TODO: io, state machine, persistent parameters, rwhandler, datatypes, features, commands, proxies

doc/source/reference.rst

@@ -12,7 +12,7 @@ Module Base Classes
 ...................
 
 .. autoclass:: frappy.modules.Module
-    :members: earlyInit, initModule, startModule
+    :members: earlyInit, initModule, startModule, initialReads
 
 .. autoclass:: frappy.modules.Readable
     :members: Status