Index: src/documentation/constructs/actions.dox
===================================================================
--- src/documentation/constructs/actions.dox	(revision 6752dc828fcabcc74aaeb4c2eee3e8ccbef34d70)
+++ src/documentation/constructs/actions.dox	(revision eee1b7b187d1af4c9cd78e2a3a4a7c9e7aada611)
@@ -22,16 +22,18 @@
  *  have to create three files of which only one actually contains more than a
  *  few lines, namely the code of the Action itself.
+ *  Each Action also derives a specific ActionState and ActionParameters for
+ *  containing the undo/redo state information and the parameters steering what
+ *  the Action does.
  *
- *  Each Action has thus three types of functionalty: do, undo, and redo.
+ *  Each Action has thus three types of functionality: do, undo, and redo.
  *
  *  The ActionRegistry contains a prototype of each Action under its token
  *  such that an instance can be retrieved by knowing this token.
  *
- *  Each Action obtains its options from a central ValueStorage such that
- *  they are independent of where the option originated from: a command line
- *  parameter, a value entered in a graphical dialog or given via the keyboard
- *  in a terminal. That's why each begins with a function call to
- *  getParametersfromValueStorage() to fill its internal Action::params
- *  structure.
+ *  Each Action can contain multiple \ref parameters in its specific ActionParameters
+ *  structure that represent the options. Executing call() first fills a dialog
+ *  with \ref queries, one for each option. The UI then tries to obtain the
+ *  values from the user. Depending on the type of the UI in use that could mean
+ *  parsing stored command line parameters or displaying a real dialog box with widgets.
  *
  *  Also there is a regression test (\ref regression-test) for each Action to
@@ -53,6 +55,6 @@
  * has to be implemented in two more functions beside the "do".
  *
- * Note that undoing means to get everything back to its original state and by
- * whatever means seem appropriate, e.g. just remvoing all inserted atoms.
+ * Note that undoing means to get everything back to its original state and by whatever
+ * means seem appropriate, e.g. remvoing all just inserted atoms.
  * To make this more elaborate it is usually very useful to store extra information
  * in the Action's state such that undo and redo can be accomplished more quickly.
@@ -70,5 +72,5 @@
  *
  *
- *  \date 2012-12-04
+ *  \date 2013-02-07
  *
  */
Index: src/documentation/constructs/constructs.dox
===================================================================
--- src/documentation/constructs/constructs.dox	(revision 6752dc828fcabcc74aaeb4c2eee3e8ccbef34d70)
+++ src/documentation/constructs/constructs.dox	(revision eee1b7b187d1af4c9cd78e2a3a4a7c9e7aada611)
@@ -30,11 +30,14 @@
  *  \li \ref molecules
  *  \li \ref observers
+ *  \li \ref parameters
  *  \li \ref parsers
  *  \li \ref qt-gui
+ *  \li \ref queries
  *  \li \ref randomnumbers
  *  \li \ref serialization
  *  \li \ref shapes
+ *  \li \ref shaperegistry
  *  \li \ref tesselation
- *  \li \ref values
+ *  \li \ref validators
  *  \li \ref world
  *
@@ -43,5 +46,5 @@
  *
  *
- * \date 2012-01-16
+ * \date 2013-02-07
  *
  */
Index: src/documentation/constructs/parameters.dox
===================================================================
--- src/documentation/constructs/parameters.dox	(revision eee1b7b187d1af4c9cd78e2a3a4a7c9e7aada611)
+++ src/documentation/constructs/parameters.dox	(revision eee1b7b187d1af4c9cd78e2a3a4a7c9e7aada611)
@@ -0,0 +1,41 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
+ */
+
+/**
+ * \file parameters.dox
+ *
+ * Created on: Jan 20, 2013
+ *    Author: ankele
+ */
+
+
+/** \page parameters Parameters
+ *
+ * A Parameter is a named variable with constraints. The constraints are
+ * defined via \ref validators.
+ *
+ * Their main purpose is to hold user input as options for \ref actions.
+ *
+ * Some important functions are:
+ *  - Parameter::set() (set a value)
+ *  - Parameter::get() (get the set value)
+ *  - Parameter::isSet() (tests whether a value was set)
+ *
+ * Setting a value not respecting the constraint will raise an ParameterException.
+ * Initially no value is set. Getting the value without having set one will
+ * also raise an ParameterException.
+ *
+ * There are also functions for string representations:
+ *  - Parameter::setAsString()
+ *  - Parameter::getAsString()
+ *
+ * Internally the value is represented by a plain member variable of the given
+ * type. The type is fixed through the template parameter of the Parameter class.
+ *
+ * \date 2013-01-28
+ *
+ */
Index: src/documentation/constructs/qt-gui.dox
===================================================================
--- src/documentation/constructs/qt-gui.dox	(revision 6752dc828fcabcc74aaeb4c2eee3e8ccbef34d70)
+++ src/documentation/constructs/qt-gui.dox	(revision eee1b7b187d1af4c9cd78e2a3a4a7c9e7aada611)
@@ -22,10 +22,13 @@
  * \section qt-gui-qt3d Qt3D and the way to get atoms and bonds displayed
  *
- * Atoms and Bonds have to displayed, the widget for this is GLWorldView. This
+ * Atoms and Bonds have to displayed, the widget for this is GLWorldView. To
  * this class belongs GLWorldScene that contains lots of GLMoleculeObject's or
- * nodes in the speak of Qt3D. We have two derived class for these kind of
+ * nodes in the speak of Qt3D. We have four derived class for these kind of
  * objects:
  * -# GLMoleculeObject_atom: for each atom,
- * -# GLMoleculeObject_bond: for each "side" of the bond.
+ * -# GLMoleculeObject_bond: for each "side" of the bond (each represents half of
+ *     the bond that join in the middle between the two atoms),
+ * -# GLMoleculeObject_molecule: for each molecule (shows a box is selected),
+ * -# GLMoleculeObject_shape: shows the shapes in the ShapeRegistry.
  *
  * We can only add new nodes to the Qt3D scene at the level of GLWorldScene,
@@ -72,7 +75,43 @@
  * Additionally, we use GLWorldScene to do some bookkeeping about all bond nodes.
  * This is not strictly required but might in general be useful. Hence, signals
- * notify GLWorldScene also about GLWorldScene::BondRemoved that are emitted by
+ * notify GLWorldScene also about GLWorldScene::bondRemoved that are emitted by
  * the node itself.
  *
- * \date 2012-01-05
+ * \section QtElementList
+ *
+ * Lists for each element how often it occures in the world. Selecting an entry
+ * calls SelectionAtomByElementAction to select all atoms of that particular
+ * element.
+ *
+ * It observes the World and performs a complete refill on any message. To reduce
+ * performance issues it marks the list as dirty and refills it the next time the
+ * GUI is idle. This way many successive changes to the world only lead to a
+ * single refill.
+ *
+ * \section QtMoleculeList
+ *
+ * Lists all the molecules currently in the world grouped by their formula.
+ * Selecting an entry calls the SelectionMoleculeByIdAction.
+ *
+ * It observes the World the same way QtElementList does.
+ *
+ * \section QtShapeController
+ *
+ * This is the interface for the ShapeRegistry. It lists all the shapes in the
+ * registry and lets the user select them. It also features buttons to call
+ * actions creating and manipulating the selected shapes.
+ *
+ * As an Observer it handles the following messages from ShapeRegistry:
+ *  - ShapeRegistry::ShapeInserted
+ *  - ShapeRegistry::ShapeRemoved
+ *  - ShapeRegistry::SelectionChanged
+ *
+ * \section QtInfoBox
+ *
+ * Shows information about the atom and molecule the cursor is currently hovering over.
+ *
+ * The info pages are Observers of the respective atom/molecule. When receiving
+ * e.g. QtAtomInfoPage::subjectKilled() they automatically clear the info box.
+ *
+ * \date 2013-02-07
  */
Index: src/documentation/constructs/queries.dox
===================================================================
--- src/documentation/constructs/queries.dox	(revision eee1b7b187d1af4c9cd78e2a3a4a7c9e7aada611)
+++ src/documentation/constructs/queries.dox	(revision eee1b7b187d1af4c9cd78e2a3a4a7c9e7aada611)
@@ -0,0 +1,55 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
+ */
+
+/**
+ * \file queries.dox
+ *
+ * Created on: Jan 20, 2013
+ *    Author: ankele
+ */
+
+
+/** \page queries Queries
+ *
+ * \section description General description
+ *
+ * Queries represent the process of asking the user to input a value as an
+ * option for \ref actions. How that is done depends on the current UI and
+ * the type of the value.
+ *
+ * \section internals Internals
+ *
+ * What happens when an action needs, say, an integer valued Parameter?
+ *  - the action object has an element of type Parameter<int> declared in its .def file (including a validator defining the constraints)
+ *  - the action's call() requests the current UI (for example QT) to create a dialog. The QT GUI creates a QtDialog
+ *  - Action::call() also calls Dialog::query<T>() for each of its parameters telling the dialog what to ask from the user later on (in this case query<Parameter<int>>() )
+ *  - Action::call() calls Dialog::display()
+ *  - for each query Dialog::display() calls Query::handle() (in non QT UIs this will read temporary input from the user)
+ *  - Dialog::display() then tests if the temporary values in all queries are valid (Query::isValid() )
+ *  - if all values are correct, they are stored in the Parameter objects (Query::setValue() )
+ *  - Action::performCall() (really perform the action)
+ *
+ * QtDialog needs to be more interactive:
+ *  - it has its own QtDialog::display()
+ *  - QtDialog::display() shows the dialog box and waits till the user closes it
+ *  - the int query is shown as an QSpinBox, any user input will call QtDialog::update()
+ *  - QtDialog::update() tests if all values are valid and enables/disables the OK button accordingly
+ *
+ * The internal workings of queries:
+ *  - Dialog::query<T>() in turn calls the virtual Dialog::queryInt(), so effectivly QtDialog::queryInt() is being called
+ *  - QtDialog::queryInt() creates a new IntQtQuery object and stores it in the dialog's query list
+ *  - class hierarchy: IntQtQuery - QtQuery<int> - TQuery<int> - Query
+ *  - the base class Query only stores additional info for the user
+ *  - TQuery stores the Parameter and the temporary value
+ *  - QtQuery is used to ignore the handle() call
+ *  - IntQtQuery sets up the input box and handles the GUI signals
+ *
+ * List queries (like QtIntsQuery) are a bit more tricky. It creates a QtIntQuery as a child. The value from the child query can be added to QtIntsQuery's list of values. To handle communication between parent and child the child is being embedded in its own (special) dialog owned by the parent.
+ *
+ * \date 2013-01-29
+ *
+ */
Index: src/documentation/constructs/shaperegistry.dox
===================================================================
--- src/documentation/constructs/shaperegistry.dox	(revision eee1b7b187d1af4c9cd78e2a3a4a7c9e7aada611)
+++ src/documentation/constructs/shaperegistry.dox	(revision eee1b7b187d1af4c9cd78e2a3a4a7c9e7aada611)
@@ -0,0 +1,33 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
+ */
+
+/**
+ * \file shaperegistry.dox
+ *
+ * Created on: Jan 28, 2013
+ *    Author: ankele
+ */
+
+/** \page shaperegistry ShapeRegistry
+ *
+ * Instances of \ref shapes with unique names can be stored inside the
+ * ShapeRegistry. They can be selected via actions.
+ *
+ * There are special action to manipulate the currently selected shapes:
+ *  - CombineShapesAction
+ *  - RemoveShapeAction
+ *  - RotateShapeAction
+ *  - StretchShapeAction
+ *  - TranslateShapeAction
+ *
+ * Some actions on the world (like selecting all atoms within a shape or
+ * filling a shape with molecules) use the currently selected shapes in
+ * the ShapeRegistry.
+ *
+ * \date 2013-01-28
+ *
+ */
Index: src/documentation/constructs/shapes.dox
===================================================================
--- src/documentation/constructs/shapes.dox	(revision 6752dc828fcabcc74aaeb4c2eee3e8ccbef34d70)
+++ src/documentation/constructs/shapes.dox	(revision eee1b7b187d1af4c9cd78e2a3a4a7c9e7aada611)
@@ -16,10 +16,11 @@
  *
  * Shapes are present for denoting a specific region of the simulation domain.
- * There are three types present:
+ * There are four primitive types present:
  *  - Sphere
  *  - Ellipsoid
  *  - Cuboid
+ *  - Cylinder
  *
- * Note that both may be modified (shrink/grow, rotate, morph) via an arbitrary
+ * Note that all may be modified (shrink/grow, rotate, morph) via an arbitrary
  * matrix.
  *
@@ -43,9 +44,9 @@
  * Cuboid(Vector(0,0,0), Vector(2,2,2)) && !Sphere(Vector(1,1,1), 1.)
  * \endcode
- * which would be match any object within the cuboid from (0,0,0) to (2,2,2)
+ * which would match any object within the cuboid from (0,0,0) to (2,2,2)
  * that is not in the unit sphere at (1,1,1).
  *
  *
- * \date 2011-10-31
+ * \date 2013-02-07
  *
  */
Index: src/documentation/constructs/validators.dox
===================================================================
--- src/documentation/constructs/validators.dox	(revision eee1b7b187d1af4c9cd78e2a3a4a7c9e7aada611)
+++ src/documentation/constructs/validators.dox	(revision eee1b7b187d1af4c9cd78e2a3a4a7c9e7aada611)
@@ -0,0 +1,41 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
+ */
+
+/**
+ * \file validators.dox
+ *
+ * Created on: Jan 20, 2013
+ *    Author: ankele
+ */
+
+
+/** \page validators Validators
+ *
+ * Validators define constraints for variables. A given variable can be
+ * testet whether or not it fulfills the constraints by executing the
+ * validator's isValid() function. Equivalently the operator::() can be used.
+ *
+ * Their main purpose is to constrain user input for \ref parameters in \ref actions.
+ *
+ * There are several general purpose validators, for example:
+ *  - DummyValidator (no constraint)
+ *  - DiscreteValidator (is the variable element of a given set)
+ *  - RangeValidator (is the variable inside a halfopen interval)
+ *  - STLVectorValidator (defines a constraint for each element and/or for the number of elements)
+ *
+ * Validators can also be joined via and/or/not operations:
+ * \code
+ * RealSpaceMatrixSymmetricValidator() && RealSpaceMatrixInvertibleValidator()
+ * \endcode
+ *
+ * The type of the variale is static. The base class Validator has a template parameter
+ * to define the type. Some derived validators don't have template parameters because
+ * they are derived from a Validator<SomeFixedType>.
+ *
+ * \date 2013-01-28
+ *
+ */
