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>

test/test_statemachine.py

@@ -249,15 +249,22 @@ class Mod(HasStates, Drivable):
         self._my_time += 1
 
 
+class Started(RuntimeError):
+    pass
+
+
 def create_module():
     updates = []
     obj = Mod('obj', LoggerStub(), {'description': ''}, ServerStub(updates))
     obj.initModule()
     obj.statelist = []
     try:
-        obj._Module__pollThread(obj.polledModules, None)
-    except TypeError:
-        pass  # None is not callable
+        def started():
+            raise Started()
+        # run __pollThread until Started is raised (after initial phase)
+        obj._Module__pollThread(obj.polledModules, started)
+    except Started:
+        pass
     updates.clear()
     return obj, updates