Index: src/documentation/Makefile.am
===================================================================
--- src/documentation/Makefile.am	(revision 48d20d12c40193473e911ec536adb1dfb3d14bff)
+++ src/documentation/Makefile.am	(revision 415ddd8a44847064389eb3783769c8531725615c)
@@ -13,4 +13,5 @@
 	${top_srcdir}/src/documentation/constructs/constructs.dox \
 	${top_srcdir}/src/documentation/constructs/descriptors.dox \
+	${top_srcdir}/src/documentation/constructs/filling.dox \
 	${top_srcdir}/src/documentation/constructs/fragmentation.dox \
 	${top_srcdir}/src/documentation/constructs/linearalgebra.dox \
@@ -18,9 +19,16 @@
 	${top_srcdir}/src/documentation/constructs/molecules.dox \
 	${top_srcdir}/src/documentation/constructs/observers_observables.dox \
+	${top_srcdir}/src/documentation/constructs/parameters.dox \
 	${top_srcdir}/src/documentation/constructs/parsers.dox \
+	${top_srcdir}/src/documentation/constructs/potentials.dox \
+	${top_srcdir}/src/documentation/constructs/qt-gui.dox \
+	${top_srcdir}/src/documentation/constructs/queries.dox \
 	${top_srcdir}/src/documentation/constructs/randomnumbers.dox \
 	${top_srcdir}/src/documentation/constructs/serialization.dox \
+	${top_srcdir}/src/documentation/constructs/shaperegistry.dox \
 	${top_srcdir}/src/documentation/constructs/shapes.dox \
 	${top_srcdir}/src/documentation/constructs/tesselation.dox \
+	${top_srcdir}/src/documentation/constructs/validators.dox \
+	${top_srcdir}/src/documentation/constructs/values.dox \
 	${top_srcdir}/src/documentation/constructs/world.dox \
 	${top_srcdir}/src/documentation/howtos/action.dox \
Index: src/documentation/userinterfaces/python.dox
===================================================================
--- src/documentation/userinterfaces/python.dox	(revision 48d20d12c40193473e911ec536adb1dfb3d14bff)
+++ src/documentation/userinterfaces/python.dox	(revision 415ddd8a44847064389eb3783769c8531725615c)
@@ -20,5 +20,5 @@
  *  script.
  *
- *  This is done in \b src/Actions/pyMoleCuilder.cpp.
+ *  This is done in \b src/Python/PythonScripting.cpp.
  *
  *  There again some preprocessor magic is happening. One the one hand we
@@ -43,7 +43,23 @@
  *  mol.SelectAtomById("0")
  *  mol.AtomRemove()
+ *  mol.wait()
+ *  mol.getSelectedMolarMass()
+ *  mol.wait()
  *  \endcode
  *  which loads a file \b test.xyz into the (internal) World, selects the first
- *  atom and removes it.
+ *  atom and removes it. Notice \b mol.wait() at the end. This might be necessary
+ *  as actions are executed in a different thread than the python script itself.
+ *  Hence, if you require values from molecuilder you have to make sure that
+ *  all your actions have been processed by this second thread. That's what
+ *  wait() is good for. It waits until action queue thread is idle. Then you
+ *  can be sure that molecuilder has removed all atoms, performed all selections
+ *  and any value you retrieve is up-to-date.
+ *
+ *  Note that there are two \b wait()s present in the example. As the Actions
+ *  are executed in another thread and the above commands just tell the MoleCuilder
+ *  library (the ActionQueue to be precise) to enqueue the requested action,
+ *  we have to wait (in the main thread) until the actions actually have been
+ *  executed before we continue (i.e. when we need the new state where the
+ *  atoms have been removed) and before we \b terminate!
  *
  *  \section userinterfaces-python-running Running a test script
@@ -72,4 +88,5 @@
  *  \code
  *  pyMoleCuilder.WorldInput("test.xyz")
+ *  pyMoleCuilder.wait()
  *  \endcode
  *
@@ -78,4 +95,5 @@
  *  \code
  *  pyMoleCuilder.SelectionAllMolecules()
+ *  pyMoleCuilder.wait()
  *  \endcode
  *
@@ -84,5 +102,13 @@
  *  \code
  *  pyMoleCuilder.SelectAtomById("0")
+ *  pyMoleCuilder.wait()
  *  \endcode
+ *
+ *  \warning Again, take note of the added wait()s that ensure the all enqueued
+ *  actions also have been executed. This is especially important in scripts as
+ *  otherwise your script may deadlock. That's because ActionQueue's destructor
+ *  waits for the thread that executes the actions to end, and in another thread
+ *  we still want to access to ActionQueue whose instance is however locked as
+ *  it is about the get destroyed.
  *
  *  \subsection userinterfaces-python-notes-cleanup Cleaning up or reset state ...
@@ -115,6 +141,23 @@
  *  gives you the docu string on WorldInputAction.
  *
+ * \subsection userinterfaces-python-notes-wait Waiting for the action queue
  *
- * \date 2013-03-18
+ * Note again that actions are executed in a different thread as the python
+ * script. Hence, we require synchronization at certain intervals where you
+ * require molecuilder to be up to speed. All commands you executed such
+ * as
+ * \code
+ * import pyMoleCuilder as mol
+ * mol.WorldInput("foo.xyz")
+ * mol.wait()
+ * \endcode
+ * just queue this specific input action but not execute it right away. That's
+ * left to the other thread. Hence, you need to wait() before:
+ * -# you access mol.get...() functions as these are not actions themselves.
+ * -# you need to have files written by molecuilder to be parsed in the python
+ *    script.
+ *
+ *
+ * \date 2013-09-28
  *
  */
