Changeset 750cff for src

Timestamp:

Oct 31, 2011, 5:13:52 PM (14 years ago)

Author:

Frederik Heber <heber@…>

Branches:

Action_Thermostats, Add_AtomRandomPerturbation, Add_FitFragmentPartialChargesAction, Add_RotateAroundBondAction, Add_SelectAtomByNameAction, Added_ParseSaveFragmentResults, AddingActions_SaveParseParticleParameters, Adding_Graph_to_ChangeBondActions, Adding_MD_integration_tests, Adding_ParticleName_to_Atom, Adding_StructOpt_integration_tests, AtomFragments, Automaking_mpqc_open, AutomationFragmentation_failures, Candidate_v1.5.4, Candidate_v1.6.0, Candidate_v1.6.1, ChangeBugEmailaddress, ChangingTestPorts, ChemicalSpaceEvaluator, CombiningParticlePotentialParsing, Combining_Subpackages, Debian_Package_split, Debian_package_split_molecuildergui_only, Disabling_MemDebug, Docu_Python_wait, EmpiricalPotential_contain_HomologyGraph, EmpiricalPotential_contain_HomologyGraph_documentation, Enable_parallel_make_install, Enhance_userguide, Enhanced_StructuralOptimization, Enhanced_StructuralOptimization_continued, Example_ManyWaysToTranslateAtom, Exclude_Hydrogens_annealWithBondGraph, FitPartialCharges_GlobalError, Fix_BoundInBox_CenterInBox_MoleculeActions, Fix_ChargeSampling_PBC, Fix_ChronosMutex, Fix_FitPartialCharges, Fix_FitPotential_needs_atomicnumbers, Fix_ForceAnnealing, Fix_IndependentFragmentGrids, Fix_ParseParticles, Fix_ParseParticles_split_forward_backward_Actions, Fix_PopActions, Fix_QtFragmentList_sorted_selection, Fix_Restrictedkeyset_FragmentMolecule, Fix_StatusMsg, Fix_StepWorldTime_single_argument, Fix_Verbose_Codepatterns, Fix_fitting_potentials, Fixes, ForceAnnealing_goodresults, ForceAnnealing_oldresults, ForceAnnealing_tocheck, ForceAnnealing_with_BondGraph, ForceAnnealing_with_BondGraph_continued, ForceAnnealing_with_BondGraph_continued_betteresults, ForceAnnealing_with_BondGraph_contraction-expansion, FragmentAction_writes_AtomFragments, FragmentMolecule_checks_bonddegrees, GeometryObjects, Gui_Fixes, Gui_displays_atomic_force_velocity, ImplicitCharges, IndependentFragmentGrids, IndependentFragmentGrids_IndividualZeroInstances, IndependentFragmentGrids_IntegrationTest, IndependentFragmentGrids_Sole_NN_Calculation, JobMarket_RobustOnKillsSegFaults, JobMarket_StableWorkerPool, JobMarket_unresolvable_hostname_fix, MoreRobust_FragmentAutomation, ODR_violation_mpqc_open, PartialCharges_OrthogonalSummation, PdbParser_setsAtomName, PythonUI_with_named_parameters, QtGui_reactivate_TimeChanged_changes, Recreated_GuiChecks, Rewrite_FitPartialCharges, RotateToPrincipalAxisSystem_UndoRedo, SaturateAtoms_findBestMatching, SaturateAtoms_singleDegree, StoppableMakroAction, Subpackage_CodePatterns, Subpackage_JobMarket, Subpackage_LinearAlgebra, Subpackage_levmar, Subpackage_mpqc_open, Subpackage_vmg, Switchable_LogView, ThirdParty_MPQC_rebuilt_buildsystem, TrajectoryDependenant_MaxOrder, TremoloParser_IncreasedPrecision, TremoloParser_MultipleTimesteps, TremoloParser_setsAtomName, Ubuntu_1604_changes, stable

Children:

5982c5

Parents:

19bc74

Message:

HUGE: Update on documenation.

• a general skeleton of the documentation is now in place with all the major components of MoleCuilder explained to some extent.
• some information has been transfered from TRAC (e.g. install procecure) into this doxygen documentation where it is general and not specific to the situation at our institute.

Location:

src

Files:

• Actions/Action.hpp (modified) (1 diff)
• builder.cpp (modified) (1 diff)
• documentation/code.dox (modified) (1 diff)
• documentation/constructs/actions.dox (modified) (1 diff)
• documentation/constructs/atoms.dox (added)
• documentation/constructs/bondgraph.dox (modified) (1 diff)
• documentation/constructs/constructs.dox (modified) (2 diffs)
• documentation/constructs/descriptors.dox (modified) (1 diff)
• documentation/constructs/fragmentation.dox (modified) (1 diff)
• documentation/constructs/linearalgebra.dox (added)
• documentation/constructs/logger.dox (added)
• documentation/constructs/molecules.dox (added)
• documentation/constructs/observers_observables.dox (modified) (1 diff)
• documentation/constructs/parsers.dox (modified) (1 diff)
• documentation/constructs/randomnumbers.dox (modified) (1 diff)
• documentation/constructs/serialization.dox (modified) (1 diff)
• documentation/constructs/shapes.dox (modified) (1 diff)
• documentation/constructs/tesselation.dox (modified) (1 diff)
• documentation/constructs/world.dox (added)
• documentation/copyright.dox (added)
• documentation/faq.dox (modified) (1 diff)
• documentation/fileformats.dox (added)
• documentation/howtos/action.dox (added)
• documentation/howtos/howtos.dox (added)
• documentation/install.dox (modified) (1 diff)
• documentation/launch.dox (modified) (1 diff)
• documentation/mainpage.dox (modified) (1 diff)
• documentation/tests/code-tests.dox (modified) (2 diffs)
• documentation/tests/regression-tests.dox (modified) (3 diffs)
• documentation/tests/tests.dox (modified) (3 diffs)
• documentation/tests/unit-tests.dox (modified) (4 diffs)
• documentation/userinterfaces/commandline.dox (added)
• documentation/userinterfaces/graphical.dox (added)
• documentation/userinterfaces/textmenu.dox (added)
• documentation/userinterfaces/userinterfaces.dox (added)

src/Actions/Action.hpp

@@ -31 +31 @@
 #include "Actions/ActionTraits.hpp"
 
-/**
- * @file
- * <H1> Action Howto </H1>
- *
- * <H2> Introduction </H2>
- *
- * Actions are used in object oriented design as a replacement for callback functions.
- * In most ways Actions can be used in the same way that callbacks were used in non
- * OO-Systems, but can contain support for several extra mechanism such as undo/redo
- * or progress indicators.
- *
- * The main purpose of an action class is to contain small procedures, that can be repeatedly
- * called. These procedures can also be stored, passed around, so that the execution of an
- * action can happen quite far away from the place of creation. For a detailed description of
- * the Action pattern see GOF:1996.
- *
- * <H3> How to use an action </H3>
- *
- * The process of using an action is as easy as calling the call() method of the action. The
- * action will then do whatever it is supposed to do. If it is an action that can be undone, it
- * will also register itself in the history to make itself available for undo. To undo the last
- * action, you can either use the undoLast() method inside the ActionHistory class or call the
- * UndoAction also provided by the ActionHistory. If an action was undone it will be available for
- * redo, using the redoLast() method of the ActionHistory or the RedoAction also provided by this
- * class. To check whether undo/redo is available at any moment you can use the hasUndo() or
- * hasRedo() method respectively.
- *
- * Note that an Action always has two functions createDialog() and performCall(). The former
- * returns a Dialog filled with query...() functions for all information that we need from the
- * user. The latter must not contain any interaction but just uses these values (which are
- * temporarily stored by class ValueStorage) to perform the Action.
- *
- * Furthermore, there is a global action function that makes the action callable with already
- * present parameters (i.e. without user interaction and for internal use within the code only).
- * This function is basically just a macro, that puts the parameters into the ValueStorage and
- * calls Action::call(Action::NonInteractive).
- *
- * Actions can be set to be active or inactive. If an action is set to inactive it is signaling, that
- * some condition necessary for this action to be executed is not currently met. For example the
- * UndoAction will set itself to inactive, when there is no action at that time that can be undone.
- * Using call() on an inactive Action results in a no-op. You can query the state of an action using
- * the isActive() method.
- *
- * The undo capabilities of actions come in three types as signaled by two boolean flags (one
- * combination of these flags is left empty as can be seen later).
- * <ul>
- * <li/> The first flag indicates if the undo mechanism for this action should be considered at all, i.e.
- *   if the state of the application changes in a way that needs to be reverted. Actions that should
- *   consider the undo mechanism are for example adding a molecule, moving atoms, changing
- *   the name of a molecule etc. Changing the View-Area on the other hand should be an action that
- *   does not consider the undo mechanism. This flag can be queried using the shouldUndo() method.
- *
- * <li/> The second flag indicates whether the changes can be undo for this action. If this flag is true
- *   the action will be made available for undo using the ActionHistory class and the actions of this
- *   class. If this flag is false while the shoudlUndo() flag is true this means that this action
- *   changes the state of the application changes in a way that cannot be undone, but might cause
- *   the undo of previous actions to fail. In this case the whole History is cleared, as to keep
- *   the state of the application intact by avoiding dangerous undos. This flag can be queried
- *   using the canUndo() method.
- *</ul>
- *
- * Each action has a name, that can be used to identify it throughout the run of the application.
- * This name can be retrieved using the getName() method. Most actions also register themselves with
- * a global structure, called the ActionRegistry. Actions that register themselves need to have a
- * unique name for the whole application. If the name is known these actions can be retrieved from
- * the registry by their name and then be used as normal.
- *
- * <H2> Building your own actions </H2>
- *
- * Building actions is easy. Each specific ...Action is derived from the base class Action.
- * In order to create all the reoccuring stuff, macros have been created which you can simply
- * include and then don't need to worry about it.
- * There are three major virtual functions: performCall(), performUndo(), performRedo() which
- * you have to write, to equip your action with some actual capabilities.
- * Each Action definition and implementation consists of of three files:
- * -# cpp: contains performX() which you have to write, also some boilerplate functions which are
- *         constructed automatically when including your def and "Actions/action_impl_pre.hpp"
- * -# hpp: boilerplate definitions created simply by including your def and
- *         "Actions/action_impl_header.hpp"
- * -# def: macro definitions of all your parameters and additional variables needed for the state,
- *         also name and category and token of your action.
- *
- * Best thing to do is look at one of the already present triples and you should soon understand
- * what you have to add:
- * -# pick the right category, i.e. the right folder in src/Actions
- * -# pick the right name
- * -# decide which parameters your actions need and what the type, the variable name and the token
- *    to reference it from the command-line should be. Check whether already present and fitting
- *    tokens exists, e.g. "position" as token for a Vector representing a position.
- * -# consider which additional information you need to undo your action
- * -# don't forget to include your .def file followed by "action_impl_pre.hpp" in .cpp or
- *    "action_impl_header.hpp" in the .hpp
- * -# continue to write the functionality of your action in performCall(), undo and redo in performUndo()
- *    and performRedo().
- * -# You should indicate whether the action supports undo by implementing the shouldUndo() and
- *    canUndo() methods to return the appropriate flags.
- *
- * <H3> Specific notes on the macros </H3>
- *
- * The following functions are created by the macros, i.e. you don't need to worry about it:
- *
- * Any user interaction should be placed into the dialog returned by fillDialog().
- *
- * Also, create the global function to allow for easy calling of your function internally (i.e.
- * without user interaction). It should have the name of the Action class without the suffix Action.
- *
- * The constructor of your derived class also needs to call the Base constructor, passing it the
- * name of the Action and a flag indicating whether this action should be made available in the
- * registry. WARNING: Do not use the virtual getName() method of the derived action to provide the
- * constructor with the name, even if you overloaded this method to return a constant. Doing this
- * will most likely not do what you think it does (see: http://www.parashift.com/c++-faq-lite/strange-inheritance.html#faq-23.5
- * if you want to know why this wont work)
- *
- * <H3> Interfacing your Action with the Undo mechanism </H3>
- *
- * The performX() methods need to comply to a simple standard to allow for undo and redo. The first
- * convention in this standard concerns the return type. All methods that handle calling, undoing
- * or redoing return an object of Action::state_ptr. This is a smart pointer to a State object, that
- * can be used to store state information that is needed by your action for later redo. A rename
- * Action for example would need to store which object has been renamed and what the old name was.
- * A move Action on the other hand would need to store the object that has been moved as well as the
- * old position. If your Action does not need to store any kind of information for redo you can
- * simply return Action::success and skip the rest of this paragraph. If your action has been
- * abborted you can return Action::failure, which indicates to the history mechanism that this
- * action should not be stored.
- *
- * If your Action needs any kind of information to undo its execution, you need to store this
- * information in the state that is returned by the performCall() method. Since no assumptions
- * can be made on the type or amount of information the ActionState base class is left empty.
- * To use this class you need to derive a YourActionState class from the ActionState base class
- * adding your data fields and accessor functions. Upon undo the ActionState object produced
- * by the corresponding performCall() is then passed to the performUndo() method which should
- * typecast the ActionState to the appropriate sub class, undo all the changes and produce
- * a State object that can be used to redo the action if neccessary. This new state object is
- * then used if the redo mechanism is invoked and passed to the performRedo() function, which
- * again produces a State that can be used for performUndo().
- *
- * <H3> Outline of the implementation of Actions </H3>
- *
- * To sum up the actions necessary to build actions here is a brief outline of things methioned
- * in the last paragraphs:
- *
- * <H4> Basics </H4>
- *
- * <ul>
- *  <li/> create parameter tupels (type, token, reference), put into def. Access them later in
- *        the performX() via the structure params.###.
- *  <li/> think of name, category and token for your action, put into def
- *  <li/> create additional state variables tupels (type, reference) for storing extra information
- *        that you need for undo/redo in the ActionState. You can always access the parameters
- *        of your Action by state.params.### (i.e. they are copied to the state by default).
- *  <li/> implement performCall(), first line should be calling of getParametersfromValueStorage().
- *  <li/> performUndo(), performRedo()
- *  <li/> implement the functions that return the flags for the undo mechanism, i.e. true/false.
- * </ul>
- *
- * <H4> Implementing performX() methods </H4>
- *
- * <ul>
- *  <li/> performCall():
- *  <ul>
- *   <li/> first line should be calling of getParametersfromValueStorage().
- *   <li/> Access your parameters by the structure params.### (where ### stands for the reference/
- *         variable name chosen in the tupel).
- *   <li/> do whatever is needed to make the action work
- *   <li/> if the action was abborted return Action::failure
- *   <li/> if the action needs to save a state return a custom state object
- *   <li/> otherwise return Action::success
- *  </ul>
- *  <li/> performUndo():
- *  <ul>
- *   <li/> typecast the ActionState pointer to a Pointer to YourActionState if necessary
- *   <li/> undo the action using the extra information and the Action's parameters in the state
- *   <li/> produce a new state that can be used for redoing and return it
- *  </ul>
- *  <li/> performRedo():
- *  <ul>
- *   <li/> take the ActionState produced by performUndo and typecast it to a pointer to YourActionState if necessary
- *   <li/> redo the undone action using the extra information and the Action's parameters in the state
- *   <li/> produce a new state that can be used by performUndo() and return it
- *  </ul>
- * </ul>
- *
- * <H2> Advanced techniques </H2>
- *
- * <H3> Predefined Actions </H3>
- *
- * To make construction of actions easy there are some predefined actions. Namely these are
- * the MethodAction and the ErrorAction.
- *
- * The method action can be used to turn any function with empty arguments and return type void
- * into an action (also works for functors with those types). Simply pass the constructor for the
- * MethodAction a name to use for this action, the function to call inside the performCall()
- * method and a flag indicating if this action should be made retrievable inside the registry
- * (default is true). MethodActions always report themselves as changing the state of the
- * application but cannot be undone. i.e. calling MethodActions will always cause the ActionHistory
- * to be cleared.
- *
- * ErrorActions can be used to produce a short message using the Log() << Verbose() mechanism of
- * the molecuilder. Simply pass the constructor a name for the action, the message to show upon
- * calling this action and the flag for the registry (default is again true). Error action
- * report that they do not change the state of the application and are therefore not considered
- * for undo.
- *
- * <H3> Sequences of Actions and MakroActions </H3>
- *
- * <H4> Building sequences of Actions </H4>
- *
- * Actions can be chained to sequences using the ActionSequence class. Once an ActionSequence is
- * constructed it will be initially empty. Any Actions can then be added to the sequence using the
- * addAction() method of the ActionSequence class. The last added action can be removed using the
- * removeLastAction() method. If the construction of the sequence is done, you can use the
- * callAll() method. Each action called this way will register itself with the History to allow
- * separate undo of all actions in the sequence.
- *
- * <H4> Building larger Actions from simple ones </H4>
- *
- * Using the pre-defined class MakroAction it is possible to construct bigger actions from a sequence
- * of smaller ones. For this you first have to build a sequence of the actions using the ActionSequence
- * as described above. Then you can construct a MakroAction passing it a name, the sequence to use
- * and as usual a flag for the registry. You can then simply call the complete action-sequence through
- * this makro action using the normal interface. Other than with the direct use of the action sequence
- * only the complete MakroAction is registered inside the history, i.e. the complete sequence can be
- * undone at once. Also there are a few caveats you have to take care of when using the MakroAction:
- * <ul>
- *  <li/> All Actions as well as the sequence should exclusively belong to the MakroAction. This
- *        especially means, that the destruction of these objects should be handled by the MakroAction.
- *  <li/> none of the Actions inside the MakroAction should be registered with the registry, since the
- *        registry also assumes sole ownership of the actions.
- *  <li/> Do not remove or add actions from the sequence once the MakroAction has been constructed, since this
- *        might brake important assumptions for the undo/redo mechanism
- * </ul>
- *
- * <H3> Special kinds of Actions </H3>
- *
- * To make the usage of Actions more versatile there are two special kinds of actions defined,
- * that contain special mechanisms. These are defined inside the class Process, for actions that
- * take some time and indicate their own progress, and in the class Calculations for actions that
- * have a retrievable result.
- *
- * <H4> Processes </H4>
- *
- * Processes are Actions that might take some time and therefore contain special mechanisms
- * to indicate their progress to the user. If you want to implement a process you can follow the
- * guidelines for implementing actions. In addition to the normal Action constructor parameters,
- * you also need to define the number of steps the process takes to finish (use 0 if that number is
- * not known upon construction). At the beginning of your process you then simply call start() to
- * indicate that the process is taking up its work. You might also want to set the number of steps it
- * needs to finish, if it has changed since the last invocation/construction. You can use the
- * setMaxSteps() method for this. Then after each finished step of calulation simply call step(),
- * to let the indicators know that it should update itself. If the number of steps is not known
- * at the time of calculation, you should make sure the maxSteps field is set to 0, either through
- * the constructor or by using setMaxSteps(0). Indicators are required to handle both processes that
- * know the number of steps needed as well as processes that cannot predict when they will be finished.
- * Once your calculation is done call stop() to let every indicator know that the process is done with
- * the work and to let the user know.
- *
- * Indicators that want to know about processes need to implement the Observer class with all the
- * methods defined there. They can then globally sign on to all processes using the static
- * Process::AddObserver() method and remove themselves using the Process::RemoveObserver()
- * methods. When a process starts it will take care that the notification for this process
- * is invoked at the right time. Indicators should not try to observe a single process, but rather
- * be ready to observe the status of any kind of process using the methods described here.
- *
- * <H4> Calculations </H4>
- *
- * Calculations are special Actions that also return a result when called. Calculations are
- * always derived from Process, so that the progress of a calculation can be shown. Also
- * Calculations should not contain side-effects and not consider the undo mechanism.
- * When a Calculation is called using the Action mechanism this will cause it to calculate
- * the result and make it available using the getResult() method. Another way to have a Calculation
- * produce a result is by using the function-call operator. When this operator is used, the Calculation
- * will try to return a previously calculated and cached result and only do any actuall calculations
- * when no such result is available. You can delete the cached result using the reset() method.
- */
 
 

src/builder.cpp

@@ -13 +13 @@
  */
 
-/*! \page Copyright notice
- *
- *  MoleCuilder - to create and alter molecular systems
- *  Copyright (C) 2010  University Bonn. All rights reserved.
- *
- */
-
-/*! \mainpage MoleCuilder - a molecular set builder
- *
- * This introductory shall briefly make acquainted with the program, helping in installing and a first run.
- *
- * \section about About the Program
- *
- *  MoleCuilder is a program, written entirely in C++, that enables the construction of a coordinate set for the
- *  atoms making up an molecule. It allows for both building of simple molecules by adding atom-wise giving bond
- *  angles and distances or absolute coordinates, but also using them as templates. Regions can be specified and
- *  ordered to be filled with a molecule in a certain manner. Greater conglomerations of molecules can be tesselated
- *  and recognized as a region themselves to be subsequently surrounded by other (surface solvated) molecules.
- *  In the end, MoleCuilder allows the construction of arbitrary nano structures, whether they be crystalline or
- *  amorphic in nature.
- *
- *
- * \section install Installation
- *
- *  Installation should without problems succeed as follows:
- *  -# ./configure (or: mkdir build;mkdir run;cd build; ../configure --bindir=../run)
- *  -# make
- *  -# make install
- *
- *  Further useful commands are
- *  -# make clean uninstall: deletes .o-files and removes executable from the given binary directory\n
- *  -# make doxygen-doc: Creates these html pages out of the documented source
- *  -# make check: Runs an extensive set of unit tests and a testsuite which also gives a good overview on the set of
- *                 functions.
- *
- * \section run Running
- *
- *  The program can be executed by running: ./molecuilder
- *
- *  MoleCuilder has three interfaces at your disposal:
- *  -# Textmenu: A simple interactive console-based menu, where awaits your choices and inputs in order to set atoms
- *               as you like
- *  -# CommandLineUI: Every command can also be chained up as a sequence of actions on the command line to be executed
- *               with any user interaction.
- *  -# GraphicalUI: A graphical user interface that also display the molecular structure being built and lots of other
- *               informations to ease the construction of bigger geometries.
- *
- *  The supported output formats right now are:
- *  -# mpqc: Configuration files of the Massively Parallel Quantum Chemistry package (Sandia labs)
- *  -# pcp: Configuration files of the Parallel Car-Parrinello program (Institute for Numerical Simulation)
- *  -# tremolo: Configuration files of TREMOLO (Institute for Numerical Simulation)
- *  -# xyz: the most basic format for the 3d arrangement of atoms consisting of a list of element and 3 coordinates.
- *
- */
 
 // include config.h

src/documentation/code.dox

@@ -14 +14 @@
 
 /**
- * \page code "How to use the code"
+ * \page code How to use the code
  *
- * \li \subpage faq "Frequently Asked Questions"
- * \li \subpage constructs "List of various rigid constructs"
- * \li \subpage howto "Howtos for specific code constructs"
+ * \li \ref faq
+ * \li \ref constructs
+ * \li \ref howto
+ *
+ *
+ * \date 2011-10-31
  *
  */

src/documentation/constructs/actions.dox

@@ -12 +12 @@
  *    Author: heber
  */
+
+/** \page actions Actions
+ *
+ *  Actions are Command patterns (http://en.wikipedia.org/wiki/Command_pattern)
+ *  to allow for undoing and redoing. Each specific Action derives from this
+ *  class to implement a certain functionality. There is a lot of preprocessor
+ *  magic implemented for making this as easy as possible. In effect you only
+ *  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 has thus three types of functionalty: 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 parameter from a central ValueStorage such that
+ *  they are independent of where the parameter 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.
+ *
+ *  Also there is a regression test (\ref regression-test) for each Action to
+ *  check that it always behaves the same no matter how much the code
+ *  implementing actually has changed.
+ *
+ * \section actions-add To add a new action ...
+ *
+ *  The following steps have to be done for adding a new action:
+ *  -# Create three new files .cpp, .def, and .hpp
+ *  -# Add the files to \b src/Actions/Makefile.am.
+ *  -# Add the name of the Action to \b src/Actions/GlobalListOfActions.hpp
+ *    such that the ActionRegistry knows about it and can instantiate a
+ *    prototype.
+ *
+ *
+ *  \date 2011-10-31
+ *
+ */

src/documentation/constructs/bondgraph.dox

@@ -12 +12 @@
  *    Author: heber
  */
+
+/** \page bondgraph BondGraph
+ *
+ * The BondGraph class contains the knowledge of when two atoms are bonded and
+ * when not. At this moment it either uses a sum of covalent bond radii or an
+ * externally given bond table that gives typical bond lengths per element.
+ *
+ * The BondGraph's main working horse is the BondGraph::CreateAdjacency()
+ * function. It is strongly connected to the following graph actions:
+ * - GraphCreateAdjacencyAction
+ * - GraphSubgraphDissectionAction
+ *
+ * Therein, the bond structure is recognized again from scratch or/and the
+ * molecules afterwards represent disconnected subgraphs.
+ *
+ * In terms of graph theory the bond graph is an undirected graph with the
+ * bond degree as its weight. Bonds are respresented by edges, the atoms
+ * represent nodes.
+ *
+ *
+ * \date 2011-10-31
+ *
+ */

src/documentation/constructs/constructs.dox

@@ -7 +7 @@
 
 /**
- * \file constructs
+ * \file constructs.dox
  *
  * Created on: Oct 11, 2011
@@ -14 +14 @@
 
 
-/*
- * \page constructs "List of various rigid constructs"
+/**
+ * \page constructs List of various rigid constructs
  *
  * The following constructs are present and should be known to you as an alphabetical list:
  *
- *  \li \subpage actions
- *  \li \subpage linearalgebra
- *  \li \subpage bondgraph
- *  \li \subpage descriptors
- *  \li \subpage fragmentation
- *  \li \subpage observers
- *  \li \subpage parsers
- *  \li \subpage randomnumbers
- *  \li \subpage serialization
- *  \li \subpage shapes
- *  \li \subpage tesselation
- *  \li \subpage world
+ *  \li \ref actions
+ *  \li \ref atom
+ *  \li \ref linearalgebra
+ *  \li \ref bondgraph
+ *  \li \ref descriptors
+ *  \li \ref fragmentation
+ *  \li \ref molecule
+ *  \li \ref observers
+ *  \li \ref parsers
+ *  \li \ref randomnumbers
+ *  \li \ref serialization
+ *  \li \ref shapes
+ *  \li \ref tesselation
+ *  \li \ref world
  *
  *  Note that the most important construct is the \subpage world "World" whose functions
  *  should absolutely be known.
  *
+ *
+ * \date 2011-10-31
+ *
  */

src/documentation/constructs/descriptors.dox

@@ -12 +12 @@
  *    Author: heber
  */
+
+/** \page descriptors Descriptors
+ *
+ * Descriptors help you to select a specific subset of a given array of
+ * elements. For the moment these elements are either instances of atom
+ * or molecule that the \ref world offers.
+ *
+ * They mostly work as an argument to either obtain a specific iterator
+ * over the elements (that silently skips all non-matching ones) or
+ * a subset.
+ *
+ * Note that the following boolean operators on descriptors work:
+ * - or
+ * - and
+ * - not
+ *
+ * Hence, these descriptors are very mighty. A typical use would be as follows:
+ * \code
+ * World::getInstance().getAllAtoms(AtomByType(1) && AtomByShape(Sphere(Vector(0,0,0), 2.)));
+ * \endcode
+ * which would return an AtomComposite of all hydrogen (Z=1) atoms within a
+ * sphere of radius 2. centered at (0,0,0).
+ *
+ * Or you may obtain iterators over a selection and use them in a loop as this:
+ * \code
+ * World::MoleculeIterator iter = World::getInstance().getMoleculeIter(MoleculeByFormula(Formula("H2O")));
+ * World::MoleculeIterator enditer = World::getInstance().moleculeEnd();
+ * std::cout << "List of all water molecules:" << std::endl;
+ * for (; iter != enditer; ++iter)
+ *  std:cout << (*iter)->getId() << std::endl;
+ * \endcode
+ *
+ * \note There is difference between Selection and Descriptor. A
+ * Descriptor is just a predicate() that selects among a given list. The current
+ * Selection (of atoms/molecules) is a Descriptor \a applied to a the total
+ * list of all atoms/molecules. Hence, a selection refers to a subset where
+ * the Descriptor is just the condition that selects such a subset.
+ *
+ * \subsection descriptors-atom Atom Descriptors
+ *
+ *  The following descriptors are present for atoms:
+ *  - by id: AtomById()
+ *  - of currently selected molecule(s): AtomsByMoleculeSelection()
+ *  - currently selected atoms: AtomsBySelection()
+ *  - within a Shape: AtomByShape()
+ *  - of specific element: AtomByType()
+ *
+ * \subsection descriptors-molecule Molecule Descriptors
+ *
+ *  The following descriptors are present for molecules:
+ *  - by formula: MoleculeByFormula()
+ *  - by id: MoleculeById()
+ *  - by name: MoleculeByName()
+ *  - of currently selected atoms: MoleculesByAtomSelection()
+ *  - by order of creation: MoleculeByOrder() (i.e. -1 is the last one, 1 is the
+ *    first ever created, ...)
+ *  - by pointer: MoleculeByPtr MoleculeByPtr()
+ *  - currently selected molecules: MoleculesBySelection()
+ *
+ *
+ * \date 2011-10-31
+ *
+ */

src/documentation/constructs/fragmentation.dox

@@ -12 +12 @@
  *    Author: heber
  */
+
+/** \page fragmentation Fragmentation
+ *
+ * Fragmentation contains all routines that are required to split a given
+ * molecular system into fragments. This is part of the so-called BOSSANOVA
+ * (Bond Order diSSection in an ANOVA-like fashion) approach to get linear
+ * scaling complexity for ab-initio quantum chemistry methods.
+ *
+ * The class Fragmentation contains with Fragmentation::FragmentMolecule()
+ * the main routine that dissect a given system and stores the fragments
+ * as configuration files.
+ *
+ * After these have been treated with a supported ab-initio solver, the
+ * energies and forces can be put together via \b joiner to approximation
+ * to the total energy and forces of the whole molecular system. Later,
+ * \b analyzer additionally gives data on how good this approximation has
+ * worked out in plotable format.
+ *
+ *
+ * \date 2011-10-31
+ *
+ */

src/documentation/constructs/observers_observables.dox

@@ -12 +12 @@
  *    Author: heber
  */
+
+/** \page observers Observers and Observables
+ *
+ * The Observer/Observerable mechanism is crucial to let different and
+ * independent components know about changes among one another. E.g. when an
+ * the element of an atom changes, the GUI (\ref graphical) needs to know
+ * about this change to plot the atom with a different color or shape.
+ *
+ * The Observer/Observerable mechanism is basically just a call-back: A
+ * class announces itself as Observable with having a specific interface
+ * of functions. Observer may signOn() to this class and have a specific
+ * function (update()) be called whenever a change occurs in the Observable
+ * class.
+ *
+ * Note that additionally an Observable may have various \a channels and
+ * Observers may signOn() to just such a channel to get a very specific
+ * update. E.g. a LinkedCell class needs to know when the position of an
+ * atom changes but it does not need to know about changes of element or
+ * velocity, ... These updates are called \a Notifications.
+ *
+ * As an example:
+ * \code
+ * World::getInstance().signOn(this, World::getInstance().getChannel(World::AtomInserted));
+ * \endcode
+ * Here, in the constructor of GLWorldView the class signs on to atoms
+ * being inserted into the World such that it can add these onto the display
+ * as well. Notifications are received via recieveNotifications(), e.g.
+ * which you have to implement for an Observer class
+ * \code
+ *   switch (notification->getChannelNo()) {
+ *   case World::AtomInserted:
+ *   {
+ *     const atom *_atom = World::getInstance().lastChanged<atom>();
+ *     emit atomInserted(_atom);
+ *     break;
+ *   }
+ * \endcode
+ * Here, we just switch over all events that we process and care about (note
+ * that we only get called for those for which we have subscribed) and proceed.
+ *
+ * \note There is a complete logging mechanism available for this. However,
+ * it has to be compiled via a specific switch (\ref install). So, when
+ * you need to know why your function isn't notified, that's the way to
+ * find out.
+ *
+ * Be wary of where the update occurs: while the World tells you about new
+ * or destroyed atoms, only the atom itself tells you when its position has
+ * changed!
+ *
+ * \section observers-world Observers and the World
+ *
+ * The World, containing the arrays of all atoms and molecules, is a bit
+ * special with these observers. E.g. when you request a non-const array
+ * of atoms you receive an ObservedIterator. That is one where automatically
+ * it is assumed that you changed something and hence update() is called
+ * after you stepped over one of its elements.
+ *
+ * Thus, use const-iterators and arrays whenever possible, first to avoid
+ * this overhead, but second to avoid making pain-in-the-ass, hard-to-find
+ * mistakes.
+ *
+ * Also, the world stores specific information about what changed in the
+ * template function World::lastChanged() where it might contain reference
+ * to an atom that is about to be destroyed or just added.
+ *
+ *
+ * \date 2011-10-31
+ *
+ */

src/documentation/constructs/parsers.dox

@@ -12 +12 @@
  *    Author: heber
  */
+
+/** \page parsers Format Parsers
+ *
+ *  Format Parsers load or save information about the World (i.e. all atoms,
+ *  contained bonds, ...) in a specific file format.
+ *
+ *  All parsers derive from FormatParser and all available instances of
+ *  FormatParser's are stored in a FormatParserStorage such that they can be
+ *  retrieved with simply knowing the associated token.
+ *
+ *  We have this storage as the FormatParser may also contain extra information
+ *  per atom (...AtomDataContainer or alikes) which should be copied when an
+ *  atom is copied. Hence, as soon as a FormatParser is accessed once it sits
+ *  in the Storage and accumulates all information. Therefore, every parser
+ *  instance is unique per type throughout the run of the program.
+ *
+ *  A specific parser can be obtained from the FormatParserStorage just by
+ *  knowing the correct keyword such as this:
+ *  \code
+ *  ParserTypes type = FormatParserStorage::getInstance().getTypeFromName("xyz");
+ *  FormatParserInterface &parser = FormatParserStorage::getInstance().get(type);
+ *  \endcode
+ *
+ *  Associated to the FormatParser's is also the ChangeTracker (\ref observers)
+ *  that observers the World and tells all parsers on program exit whether
+ *  to save or not (i.e. whether any changes occurred). FormatParser_common
+ *  makes sure that each FormatParser signUp()s to this ChangeTracker.
+ *
+ *  Important is also the concept of a Parameter here. A Parameter is a value
+ *  of a certain type with a given valid range or set of valid values. There
+ *  ContinuousValue and DiscreteValue template classes that are subsequently
+ *  joined with a name to give a ContinuousParameter and DiscreteParameter to
+ *  be stored via a unifying ParameterInterface into a ParameterStorage. Such
+ *  an instance each of the FormatParser's contains. Therein extra information
+ *  such as a basis set, unit length, energy cutoff or other parser-specific
+ *  parameters are stored.
+ *
+ *  Various actions (WorldInputAction, WorldOuputAction, AtomSaveSelectedAtomsAction,
+ *  MoleculeSaveSelectedAction) use the parser to load or store atoms or to
+ *  control the behavior of storage (ParserSetOutputFormatAction, ...)
+ *
+ * \section parsers-add To add a new parser ...
+ *
+ *  The following tasks are necessary:
+ *  -# think of unique brief name for your parser, e.g. "xyz" and add to
+ *  \b ParserTypes.def. This will inform FormatParserStorage of your new parser.
+ *  (Again there is some preprocessor magic for instanting all ...)
+ *  -# Implement a FormatParserTraits specialization with some common stuff to
+ *    your parsers
+ *  \code
+ *  template<>
+ *  struct FormatParserTrait<name>
+ *  {
+ *    //!> Name of the parser
+ *    static const std::string name;
+ *    //!> suffix of the files the parser understands to read and write
+ *    static const std::string suffix;
+ *    //!> ParserTypes enumeration for the parser
+ *    static const enum ParserTypes type;
+ *  };
+ *  \endcode
+ *  where \a name is the name unique name of your parser, e.g. \a xyz.
+ *  -# Create all these static variables with matching contents.
+ *  -# Implement a FormatParser specialization
+ *  \code
+ *  template <>
+ *  class FormatParser< name >  : virtual public FormatParserInterface, public FormatParser_common
+ *  {
+ *  ...
+ *  };
+ *  \endcode
+ *  where \a name is again the name of your parser. FormatParser_common
+ *  contains some functionality common to all Parsers where FormatParserInterface
+ *  is the interface where load() and save() are defined. This allows for storage
+ *  in FormatParserRegistry.
+ *  -# implement FormatParserInterface::load() and FormatParserInterface::save().
+ *  -# implement FormatParser_common::AtomInserted() and
+ *    FormatParser_common::AtomRemoved()
+ *
+ *
+ * \date 2011-10-31
+ */

src/documentation/constructs/randomnumbers.dox

@@ -12 +12 @@
  *    Author: heber
  */
+
+/** \page randomnumbers Random Number Generation
+ *
+ * There is a factory for random number generators present. This implementation
+ * has been necessary due to lack of a common interface on the side of the
+ * boost::random programmer. Hence, we added a RandomNumberInterface for both
+ * engine and distribution and a factory for both and finally the conglomerate
+ * for combining both into a single RandomNumberGenerator.
+ *
+ * Whereever random numbers should be picked with a varying distribution or
+ * even better a user-controlled one, this RandomNumberGenerator should be
+ * used, e.g. as this
+ * \code
+ * RandomNumberGenerator &random = RandomNumberGeneratorFactory::getInstance().makeRandomNumberGenerator();
+ * const double rng_min = random.min();
+ * const double rng_max = random.max();
+ * \endcode
+ * This returns a reference to a random number generator instance. And also we obtain
+ * its RandomNumberGenerator::min() and RandomNumberGenerator::max() values.
+ * Then, we may create random values as simple as this:
+ * \code
+ * double random_value = (random()/((rng_max-rng_min)/2.) - 1.);
+ * \endcode
+ * which creates a random value within [-1,1]. Note that random() here is
+ * RandomNumberGenerator::operator() and not some global function.
+ *
+ * \note Do not necessarily use the random number generation when just a uniform
+ * distribution is required. The implementation is especially designed to allow
+ * the user control over the random number distribution. E.g. when filling the void
+ * space in a simulation box with molecules he may choose a discrete distribution
+ * with a small number of values to have a few, but random orientations of the
+ * molecules (MoleculeFillVoidWithMoleculeAction()).
+ *
+ * \date 2011-10-31
+ *
+ */

src/documentation/constructs/serialization.dox

@@ -14 +14 @@
  *    Author: heber
  */
+
+/** \page serialization Serialization
+ *
+ *  Serialization is a mighty concept. The is only possible within an object-
+ *  oriented framework. The member variables of a class make up its internal
+ *  state. By storing this state, creating another instance and restoring
+ *  the variables to this state, we may in essence clone the instance. However,
+ *  we obtain additional control as to the moment of restoration because the
+ *  internal state is stored temporarily. To allow for this storage all of
+ *  these variables have to be \e serialized.
+ *
+ *  Serialization refers to putting one after another into a writable form
+ *  (e.g. convert to string and write into a stringstream) and eventually
+ *  in reverse order to read them one by one from this writable form and
+ *  cast them back into their original type.
+ *
+ *  Here, this is done via boost::serialization.
+ *
+ *  \attention The serialization headers do not mingle well with \b MemDebug.hpp.
+ *  Hence, place them before MemDebug.hpp as they do funny stuff with the
+ *  new() operator.
+ *
+ *  Serialization is so powerful because the stored state can be stored to
+ *  disk, transfered to another thread or even to another computer. If received
+ *  by a compatible code, the instance is recreated and computation can be
+ *  continued elsewhere.
+ *
+ *  For the moment we use it for creating an undo state within the Action's.
+ *  I.e. we store the state of all instances that are modified by an Action's
+ *  doings and may in Action::performUndo() just re-create the unmodified
+ *  instance by loading them from the serializing archive.
+ *
+ *  \section serialization-add How to make your class serializable.
+ *
+ *  \subsection serialization-add-simple The simple case
+ *
+ *  All you need to do with your newly created class foo is this:
+ *  \code
+ *  class foo {
+ *  ...
+ *  private:
+ *    friend class boost::serialization::access;
+ *    template<class Archive>
+ *    void serialize(Archive & ar, const unsigned int version) const
+ *    {
+ *      ar & content;
+ *    }
+ *    ...
+ *    double content;
+ *  };
+ *  \endcode
+ *  This will implement a serialization function for both directions for the
+ *  member variable content. I.e. we may now store a class instance as this:
+ *  \code
+ *  #include <boost/archive/text_oarchive.hpp>
+ *  std::stringstream stream;
+ *  boost::archive::text_oarchive oa(stream);
+ *  oa << diagonal;
+ *  \endcode
+ *  This will store the state of the class in the stringstream \a stream.
+ *  Getting the instance back is then as easy as
+ *  \code
+ *  #include <boost/archive/text_iarchive.hpp>
+ *  boost::archive::text_iarchive ia(stream);
+ *  RealSpaceMatrix *newm;
+ *  ia >> newm;
+ *  \endcode
+ *
+ *  \subsection serialization-add-complicated The more complicated case
+ *
+ *  It gets trickier when load and store need to be done differently, e.h.
+ *  \code
+ *  class foo {
+ *  ...
+ *  private:
+ *    friend class boost::serialization::access;
+ *    // serialization
+ *    template<class Archive>
+ *    void save(Archive & ar, const unsigned int version) const
+ *    {
+ *      ar & content;
+ *    }
+ *    template<class Archive>
+ *    void load(Archive & ar, const unsigned int version)
+ *    {
+ *      ar & content;
+ *      createViews();
+ *    }
+ *    BOOST_SERIALIZATION_SPLIT_MEMBER()
+ *    ...
+ *  }
+ *  \endcode
+ *  Here, we split serialize() function into distinct load() and save() because
+ *  we have to call an additional function to fully re-store the instance, i.e.
+ *  it creates some internal reference arrays (Views) in a specific manner.
+ *
+ *  The serialize functions can also be added externally, i.e. outside of the
+ *  scope of the class, but can then access only public members (except we
+ *  again make it a friend).
+ *
+ *
+ * \date 2011-10-31
+ */

src/documentation/constructs/shapes.dox

@@ -12 +12 @@
  *    Author: heber
  */
+
+/** \page shapes Shapes
+ *
+ * Shapes are present for denoting a specific region of the simulation domain.
+ * There are three types present:
+ *  - Sphere
+ *  - Ellipsoid
+ *  - Cuboid
+ *
+ * Note that both may be modified (shrink/grow, rotate, morph) via an arbitrary
+ * matrix.
+ *
+ * The shapes are for the moment only used within \ref descriptors to specify
+ * a specific subset of atoms, here that reside in a certain region of the
+ * simulation domain.
+ *
+ * \todo There is a certain relation between Tesselation and Shape. Hence, later
+ * Tesselation shall itself be a Shape, i.e. that describes a certain region in
+ * space, here via a tesselated mesh.
+ *
+ * Again, Shapes can be joined via boolean operators:
+ * - add
+ * - or
+ * - not
+ *
+ * And thus are a very powerful concept.
+ *
+ * E.g. a shape can be used like this
+ * \code
+ * 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)
+ * that is not in the unit sphere at (1,1,1).
+ *
+ *
+ * \date 2011-10-31
+ *
+ */

src/documentation/constructs/tesselation.dox

@@ -12 +12 @@
  *    Author: heber
  */
+
+/** \page tesselation Tesselation
+ *
+ * Tesselation is a first step towards recognizing molecular surfaces.
+ *
+ * Within the code it is used for calculating correlation functions with regard
+ * to such a surface.
+ *
+ * \section tesselation-procedure
+ *
+ * In the tesselation all atoms act as possible hindrance to a rolling sphere
+ * that moves in from infinity. whenever it rests uniquely on three distinct
+ * points (atoms) a triangle is created. The algorithm continues by flipping the
+ * sphere over one of the triangle's edges to eventually obtain a closed,
+ * tesselated surface of the molecule.
+ *
+ * \note This mesh is different to the usual sense of a molecular surface as
+ * atoms are directly located on it. Normally, one considers a so-called
+ * Van-der-Waals sphere around the atoms and tesselates over these. However,
+ * the mesh can easily be modified and even expanded to match the other
+ * (although the code for that is not yet fully implemented).
+ *
+ * \section tesselation-extension
+ *
+ * The main problem for extending the mesh to match with the normal sense is
+ * that triangles may suddenly intersect others when we have the case of a non-
+ * convex mesh (which is rather the normal case). And this has to be
+ * specifically treated. Also, it is not sure whether the procedure of
+ * expanding our current surface is optimal and one should not start on a
+ * different set of nodes created from virtual points resting on the
+ * van-der-Waals spheres.
+ *
+ * \date 2011-10-31
+ *
+ */

src/documentation/faq.dox

@@ -16 +16 @@
 
 /**
- * \page faq "Frequently Asked Questions"
+ * \page faq Frequently Asked Questions
  *
  *  TODO: Documentation - add FAQ
  *
+ *
+ * \date 2011-10-31
+ *
  */

src/documentation/install.dox

@@ -13 +13 @@
  */
 
-/* \page install Installation
+/**
+ *  \page install Installation
  *
- *  Installation should without problems succeed as follows:
- *  -# ./configure (or: mkdir build;mkdir run;cd build; ../configure --bindir=../run)
- *  -# make
- *  -# make install
+ * \section install-compiling Compiling the Code
+ *
+ * After you obtained the code, you do the following:
+ *
+ * \code
+ * ./bootstrap
+ * \endcode
+ *
+ * This creates the necessary autoconf and automake files.
+ *
+ * After this,
+ *
+ * \code
+ * mkdir build
+ * cd build
+ * ../configure --prefix=`pwd`
+ * \endcode
+ *
+ * which will run the configure script that checks whether you have a current
+ * version of the following required packages
+ *
+ * -# GNU Scientific Library (specify via LDFLAGS, ...)
+ * -# Qt4 framework (--with-Qt=<dir> or --with-Qt-include-dir, --with-Qt-bin-dir,
+ *  --with-Qt-lib-dir and --with-Qt-lib)
+ * -# Boost library 1.40 or newer with program_options and threads (--with-boost=<dir>)
+ * -# CPPUnit framework (--with-cppunit-prefix=<dir>)
+ * -# CodePatterns (--with-codepatterns=<dir>)
+ *
+ * \a --prefix is the argument to tell configure where all program code should go
+ * to (pwd is the unix command for the current working directory). There are
+ * others, see
+ *
+ * \code
+ * ../configure --help
+ * \endcode
+ *
+ * and some enable/disable switches you should check out:
+ *
+ * - \a --enable-ecut - says that the TestRunner, comprising all unit tests in one
+ *  exectuable, shall make use of the Eclipse CppUnitTest (ECUT). If this is
+ *  started within eclipse with this plugin installed, a shiny interface will tell
+ *  you what failed and what not.
+ * - \a --enable-debug - activates many internal asserts, memory debugger and more
+ *  (makes code a lot slower but gives information in case something fails)
+ *
+ * \note A note about configure: If one library is found only under some specific path, you
+ * can add CFLAGS, CPPFLAGS, LDFLAGS, ... to the configure call, like this
+ * \code
+ * ../configure --prefix=`pwd` --enable-hydrogen CFLAGS="-Wall -g3" CXXFLAGS="-Wall -g3"
+ * \endcode
+ * which enables all compiler warnings and full debugging of the code without any
+ * optimization. configure saves these variables, too, such that when it is called
+ * to re-configure it will still make use of them from its cache file.
+ *
+ * There are several flags that change the way molecuilder is compiled and probably
+ * make it run faster, more unsafe, ...
+ * -# \a -DLOG_OBSERVER,  What the Observers do is logged, the log is printed on exit
+ * -# \a -DNO_MEMDEBUG,   MemDebug (memory debugger) is disabled
+ * -# \a -DNO_CACHING,  Cachable are short-wired, i.e. always recalculate, this slows
+ *  down the code a lot
+ * -# \a -DNDEBUG,  include NO_MEMDEBUG, also ASSERTs are not checked, this speeds up
+ *  the code by a factor of 5
+ *
+ * \section install-install Installing
+ *
+ * Now, we are ready to compile and install.
+ *
+ * \code
+ * make
+ * make install
+ * \endcode
+ *
+ * \attention If you have a multi-core system, it is highly recommended to use the
+ * \a -j option of make to allow for multiple threads to work on compiling or
+ * checking the codfe simultaneously.
+ *
+ * And if everything went well, you should launch the unit tests and the testsuite
+ * by (see section \ref tests on how to launch the tests individually)
+ *
+ * \code
+ * make check
+ * \endcode
+ *
+ * If everything is OK, you have a working version of MoleCuilder in form of the
+ * executables \b bin/molecuilder and \b bin/molecuildergui.
+ *
+ * If you have to delete all compiled stuff, enter
+ *
+ * \code
+ * make clean
+ * \endcode
+ *
+ * or
+ *
+ * \code
+ * make distclean
+ * \endcode
+ *
+ * which will also delete all autoconf stuff for configure.
+ *
+ * distclean is at times necessary when stuff does not compile and there's
+ * seemingly no logic behind it, i.e. especially when paths of modules have
+ * changed. To recover your configure options, either look at \b config.log in
+ * the build directory or enter
+ *
+ * \code
+ * ./config.status --version
+ * \endcode
  *
  *  Further useful commands are
- *  -# make clean uninstall: deletes .o-files and removes executable from the given binary directory\n
- *  -# make doxygen-doc: Creates these html pages out of the documented source
- *  -# make check: Runs an extensive set of unit tests and a testsuite which also gives a good overview on the set of
- *                 functions.
+ *  -# make clean uninstall: deletes .o-files and removes executable from the given
+ *    binary directory
+ *  -# make doc: Creates these html pages out of the documented source
+ *  -# make check: Runs an extensive set of unit tests and a testsuite which also gives
+ *    a good overview on the set of functions.
+ *
+ * \date 2011-10-31
  */

src/documentation/launch.dox

@@ -13 +13 @@
  */
 
-/*
- * \subpage launch Running the code
+/**
+ * \page launch Running the code
  *
- *  The program can be executed by running: ./molecuilder
+ *  Before you have done
+ *  \code
+ *  make install
+ *  \endcode
+ *  The executables are in the \b src folder of your build directory. There are
+ *  two variants:
+ *  - molecuilder (contains command line and text interface)
+ *  - molecuildergui (contains graphical user interface)
  *
- *  MoleCuilder has three interfaces at your disposal:
- *  -# Textmenu: A simple interactive console-based menu, where awaits your choices and inputs in order to set atoms
- *               as you like
- *  -# CommandLineUI: Every command can also be chained up as a sequence of actions on the command line to be executed
- *               with any user interaction.
- *  -# GraphicalUI: A graphical user interface that also display the molecular structure being built and lots of other
- *               informations to ease the construction of bigger geometries.
+ *  The programs can be executed by running:
+ *  - Text menu: Launching molecuilder with no options always gives the text menu.
+ *    \code ./molecuilder \endcode
+ *  - Command line menu: Depends on what you want, but an exemplary call is
+ *    \code ./molecuilder -i test.xyz -o tremolo xyz -v 3 --add-atom H --position "0,0,0"\endcode
+ *  - Graphical menu
+ *    \code ./molecuildergui \endcode
  *
- *  The supported output formats right now are:
- *  -# mpqc: Configuration files of the Massively Parallel Quantum Chemistry package (Sandia labs)
- *  -# pcp: Configuration files of the Parallel Car-Parrinello program (Institute for Numerical Simulation)
- *  -# tremolo: Configuration files of TREMOLO (Institute for Numerical Simulation)
- *  -# xyz: the most basic format for the 3d arrangement of atoms consisting of a list of element and 3 coordinates.
+ * The user interface are explained in greater detail in \ref userinterfaces.
  *
- *  \section
+ *
+ * \date 2011-10-31
  *
  */

src/documentation/mainpage.dox

@@ -22 +22 @@
  */
 
-/*! \mainpage MoleCuilder - a molecular set builder
+/** \mainpage MoleCuilder - a molecular set builder
  *
- * This introductory shall briefly make acquainted with the program, helping in installing and a first run.
+ * This is the main page of the Doxygen documentation of \e MoleCuilder. We give
+ * a brief description what the program is intended to do and then branch via
+ * the contents of this documentation into various topics.
  *
  * \section about About the Program
  *
- *  MoleCuilder is a program, written entirely in C++, that enables the construction of a coordinate set for the
- *  atoms making up an molecule. It allows for both building of simple molecules by adding atom-wise giving bond
- *  angles and distances or absolute coordinates, but also using them as templates. Regions can be specified and
- *  ordered to be filled with a molecule in a certain manner. Greater conglomerations of molecules can be tesselated
- *  and recognized as a region themselves to be subsequently surrounded by other (surface solvated) molecules.
- *  In the end, MoleCuilder allows the construction of arbitrary nano structures, whether they be crystalline or
- *  amorphic in nature.
+ *  MoleCuilder is a program, written entirely in C++, that enables the
+ *  construction of a coordinate set for the atoms making up an molecule. It
+ *  allows for both building of simple molecules by adding atom-wise giving bond
+ *  angles and distances or absolute coordinates, but also using them as
+ *  templates. Regions can be specified and ordered to be filled with a molecule
+ *  in a certain manner. Greater conglomerations of molecules can be tesselated
+ *  and recognized as a region themselves to be subsequently surrounded by other
+ *  (surface solvated) molecules. In the end, MoleCuilder allows the construction
+ *  of arbitrary nano structures, whether they be crystalline or amorphic in
+ *  nature.
  *
- *  For copyright see \subpage copyright.
+ *  For copyright see \ref copyright.
  *
- * \section Contents
+ * \section idea The central idea behind the program
+ *
+ * What are the central ideas?
+ *
+ * - Testedness: See \ref tests-policy which is meant \e seriously. Nothing is
+ *   worse than one version behaving different to the next with respect to
+ *   output.
+ * - Re-usability: Every piece of functionality should be easy to re-use at
+ *   someplace else. Say no to specialized one-purpose scripts, say yes to
+ *   a LEGO-like system of building your world.
+ * - Extendability: It's easy to add a new piece to the code. And it is even
+ *   more so, if you have read this documentation and know what's all already
+ *   in place.
+ * - Userfriendliness: Every Action can be undone, every Action gives lots
+ *   of output (if desired) to tell you what's going on. It's easy to save
+ *   files in between. There are also three kinds of GUIs, each of which
+ *   have the same functionality.
+ *
+ * \section contents Contents
  *
  * This manual is divided into the following sections:
- * \li \subpage install "Installation Instructions"
- * \li \subpage test "Automated testing"
- * \li \subpage launch "Launching the Code"
- * \li \subpage code "How to the use and extend the code"
+ * \li \ref install
+ * \li \ref tests
+ * \li \ref launch
+ * \li \ref debug
+ * \li \ref code
+ * \li \ref fileformats
+ *
+ * \date 2011-10-31
  *
  */

src/documentation/tests/code-tests.dox

@@ -22 +22 @@
  * -# Every .cpp files must include \b config.h and \b CodePatterns/MemDebug.hpp
  * -# Every .hpp files must include \b config.h
+ * -# Every .dox file contains a (correctly formatted: YYYY-MM-DD) date stamp.
  *
  * These make sure that the memory debugger is catching every movement on the
- * heap and that every module knows about the behavior controling defines that
- * are checked by autoconf and written to \b config.h in the build directory.
+ * heap and that every module knows about the behavior controling \e #define's that
+ * are checked by autoconf and written to \b config.h in the build directory. And
+ * also that for every documentation file it is known when it was current.
  *
- * \section Directory structure
+ * \section codetest-structure Directory structure
  *
  * The code tests are contained in \b tests/CodeChecks. Therein are all test
@@ -33 +35 @@
  * Mostly, these look through files
  *
- * \section Launching all tests
+ * \section codetest-launch-all Launching all tests
  *
- *  TODO: Documentation - explain how to launch all code tests.
+ *  In order to launch all tests, simply do:
+ *  -# Enter \b tests/CodeChecks in your build directory
+ *  -# Run
+ *    \code make check \endcode
+ *    there
  *
- * \section Launching some tests
+ * \section codetest-launch-some Launching some tests
  *
- *  TODO: Documentation - explain how to launch some code tests
+ *  Launching a single or just some of the tests is only a little bit more
+ *  complicated. Proceed as follows:
+ *  -# Enter \b tests/CodeChecks in your build directory
+ *  -# Run
+ *  \code ../../../tests/CodeChecks/testsuite <option> AUTOTEST_PATH="<buildpath>/src" \endcode,
+ *  where \a <option> is explained in the subsections below and \a <buildpath> is
+ *  the build path (i.e. the variable \a AUTOTEST_PATH should contain the path to
+ *  the executable).
  *
- * \section Inspecting results
+ *  \subsection regressiontest-launch-by-number ... by number
  *
- *  TODO: Documentation - explain how to inspect code test results.
+ *    Tests can be launched by specifying their test number, e.g. then \a <option>
+ *    might be \a 1 or \a 1-2 or just nothing for all of them.
+ *
+ *  \subsection regressiontest-launch-by-keyword .. by keyword
+ *
+ *    Tests may as well be launched by some keywords, e.g. each code check has
+ *    a specific keyword which is given via \b AT_KEYWORD directive of Autotest.
+ *    I.e. we may launch the test on \b config.h presence via the \a <option>
+ *    \a -k \a config_h. Also multiple keywords may be given.
+ *
+ * \section codetest-results Inspecting results
+ *
+ *  The testsuite can be launched with the additional option of \a -d which leaves the
+ *  directory of the test present even though the test has passed for inspection.
+ *
+ *  If a test fails, in whatever way it was launched, will leave in the build directory
+ *  a folder \b tests/CodeChecks/testsuite.dir/<nr> where \a <nr> is the number of the
+ *  test (padded maybe with some zeros).
+ *
+ *  In the current state tests will fail because one file does not include \b
+ *  config.h or \b MemDebug.hpp. Hence, check the testsuite's log to get the file
+ *  name of the culprit at its very bottom.
+ *
+ * \section unittest-add Adding new tests
+ *
+ *  \attention Name convention of files, (no spaces, use underscore) e.g.
+ *  \b testsuite-config_h.at
+ *  - the test script file should be called as follows:
+ *    -# testsuite-...
+ *    -# followed by the construct that is tested.
+ *
+ *  In order to add a new test, you have to do the following:
+ *  -# Add a new \b testsuite-....at script to the folder \b tests/CodeChecks
+ *    (have a look at the present ones and see above for help on the commands
+ *    recognized by Autotest. \e Mind \e giving it a suitable \e keyword!).
+ *  -# Add the file to Makefile.am such that the testsuite is re-created when
+ *    you change the test script.
+ *  -# Add the file as an \e m4_include directive to testsuite.at.
+ *
+ *
+ * \date 2011-10-31
  *
  */

src/documentation/tests/regression-tests.dox

@@ -25 +25 @@
  * regression tests.
  *
- * \section Directory structure
+ * \section regressiontest-structure Directory structure
  *
  * They are contained in the source folder \b tests/regression. There are
@@ -36 +36 @@
  *  named test script one directory level higher.
  *
- *  \section Adding a new test
+ *  \section regressiontest-launch-all Launching all tests
+ *
+ *  Launching all regression tests is as simple as:
+ *  -# Enter the build directory
+ *  -# There, enter \b tests/regression
+ *  -# Run
+ *  \code make check \endcode
+ *  (at you liberty with option \a -j8 or similar for running the tests in
+ *  parallel.
+ *
+ *  \section regressiontest-launch-some Launching a specific tests
+ *
+ *  Launching a single or just some of the tests is only a little bit more
+ *  complicated. There are two options: either by the test number which however
+ *  changes when new tests are added, and by keywords.
+ *
+ *  Then proceed as follows:
+ *  -# Enter the build directory
+ *  -# There, enter \b tests/regression
+ *  -# Run
+ *  \code ../../../tests/regression/testsuite <option> AUTOTEST_PATH="<buildpath>/src" \endcode,
+ *  where \a <option> is explained in the subsections below and \a <buildpath>
+ *  is the build path (i.e. the variable \a AUTOTEST_PATH should contain the
+ *  path to the executable).
+ *
+ *  \subsection regressiontest-launch-by-number ... by number
+ *
+ *    Tests can be launched by specifying their test number, e.g. then \a <option>
+ *    might be \a 283 or \a 283-284 or \a 283,285-286 or alike
+ *
+ *  \subsection regressiontest-launch-by-keyword .. by keyword
+ *
+ *    Tests may as well be launched by some keywords, e.g. each Action has a
+ *    specific token which is also one of its keyword (see above for the
+ *    policy). I.e. we may launch the test on fill-void via the \a <option>
+ *    \a -k \a fill-void. Also multiple keywords may be given.
+ *
+ * \section regressiontest-results Inspecting test results
+ *
+ *  The testsuite can be launched with the additional option of \a -d which
+ *  leaves the directory of the test present even though the test has passed
+ *  for inspection.
+ *
+ *  If a test fails, in whatever way it was launched, will leave in the build
+ *  directory a folder \b tests/regression/testsuite.dir/<nr> where \a <nr> is
+ *  the number of the test (padded maybe with some zeros).
+ *
+ * \section regressiontest-add Adding a new test
+ *
+ *  \attention Name convention of files and directories, e.g.
+ *  \b tests/regression/Parser/Pdb with \b testsuite-parser-pdb-save.at
+ *  - the test directory should either be called as the token of the Action it
+ *    tests or a unique and brief description but with no spaces, no dashes,
+ *    but CamelCase (i.e. Capitalize each new word)
+ *  - the test script file should be called as follows:
+ *    -# testsuite-...
+ *    -# ...each directory (non-capital letters) with a dash...
+ *    -# ..the name of the test directory...
+ *    -# a further description of there are multiple test scripts in the
+ *      test directory.
  *
  *  Adding a new regression tests consists of the following items:
@@ -51 +110 @@
  *  testsuite is automatically re-compiled when one of the test files has changed.
  *
- *  \section Launching all tests
  *
- *  Launching all regression tests is as simple as:
- *  -# Enter the build directory
- *  -# There, enter \b tests/regression
- *  -# Run
- *  \code make check \endcode
- *  (at you liberty with option \a -j8 or similar for running the tests in parallel.
- *
- *  \section Launching a specific tests
- *
- *  Launching a single or just some of the tests is only a little bit more complicated.
- *  There are two options: either by the test number which however changes when new
- *  tests are added, and by keywords.
- *
- *  Then proceed as follows:
- *  -# Enter the build directory
- *  -# There, enter \b tests/regression
- *  -# Run
- *  \code ../../../tests/regression/testsuite <option> AUTOTEST_PATH="<buildpath>/src" \endcode,
- *  where \a <option> is explained in the subsections below and \a <buildpath> is the build
- *  path (i.e. the variable \a AUTOTEST_PATH should contain the path to the executable).
- *
- *  \subsection ... by number
- *
- *    Tests can be launched by specifying their test number, e.g. then \a <option>
- *    might be \a 283 or \a 283-284 or \a 283,285-286 or alike
- *
- *  \subsection .. by keyword
- *
- *    Tests may as well be launched by some keywords, e.g. each Action has a specific
- *    token which is also one of its keyword (see above for the policy). I.e. we may
- *    launch the test on fill-void via the \a <option> \a -k \a fill-void. Also
- *    multiple keywords may be given.
- *
- * \section Inspecting test results
- *
- *  The testsuite can be launched with the additional option of \a -d which leaves the
- *  directory of the test present even though the test has passed for inspection.
- *
- *  If a test fails, in whatever way it was launched, will leave in the build directory
- *  a folder \b tests/regression/testsuite.dir/<nr> where \a <nr> is the number of the
- *  test (padded maybe with some zeros).
+ * \date 2011-10-31
  *
  */

src/documentation/tests/tests.dox

@@ -25 +25 @@
  * testing. Tests are regarded here as a kind of contract. The code itself is
  * just one hand in two hands shaking, the other hand is resembled by the tests
- * that checks whether the code does exactly what it's supposed to do. Without
- * testing a larger project is impossible because it cannot evolve. With
- * increasing size, a project must be refactored
- * (http://en.wikipedia.org/wiki/Code_refactoring) such that new code does not
- * have to wiggle itself around the same old issues that are present from the
- * start. Before one starts refactoring, it must be assured by some means that
- * the code before and after behaves the same with respect to its intended
- * functionality. These means are the tests.
+ * that check whether the code does exactly what it's supposed to do. Without
+ * testing a larger project is impossible because it cannot evolve: The old
+ * addage and compromises grow and grow. With increasing size, a project must be
+ * refactored (http://en.wikipedia.org/wiki/Code_refactoring) such that new code
+ * does not have to wiggle itself around the same old issues that are
+ * inadvertently and unavoidably present from the start. Before one starts
+ * refactoring, it must be assured by some means that the code before and after
+ * behaves the same with respect to its intended functionality. These means are
+ * the tests.
  *
- * Unit tests (http://en.wikipedia.org/wiki/Unit_testing) tests single
- * components (e.g. classes), dependencies on other classes are often just
- * mimicked via so-called stubs. These test whether a component always behaves
- * as desired.
+ * Unit tests (http://en.wikipedia.org/wiki/Unit_testing) check on single
+ * components (e.g. classes), dependencies of the components on other classes
+ * with the test frame are often just mimicked via so-called stubs (sort of
+ * dummy components that don't calculate or do anything but return an expected
+ * result suitable for this test only, see http://en.wikipedia.org/wiki/Test_stubs).
+ * These test whether a component always behaves as desired.
  *
  * Regression test (http://en.wikipedia.org/wiki/Regression_testing) on the other
@@ -45 +48 @@
  * has not changed the outcome of older functions.
  *
+ * \section tests-launch-all Launching all tests
+ *
  * Note that all tests can be launched via
  * \code make check \endcode
  * in the top build directory.
  *
- * \section Policy on launching tests
+ * \section tests-policy Policy on launching tests
  *
  * Note that the above run of \e all \e tests \e should \e pass for each and
@@ -60 +65 @@
  * runs fine and produces a distributable archive.
  *
+ * \date 2011-10-31
+ *
  */

src/documentation/tests/unit-tests.dox

@@ -18 +18 @@
  * Unit tests are done via the CppUnit framework (http://cppunit.sourceforge.net/doc/1.8.0/).
  *
- * \section Directory structure
+ * \section unittest-structure Directory structure
  *
  *  Unit tests are always located in a subfolder \b unittests of the component
@@ -24 +24 @@
  *  resides in \b src/Parser/unittests.
  *
- * \section Adding new tests
- *
- *  TODO: Documentation - explain how to add tests.
- *
- * \section Launching all tests
+ * \section unittest-launch-all Launching all tests
  *
  *  All unit tests can be launched as follows:
@@ -39 +35 @@
  * This will run all present unit tests one after the other.
  *
- * \section Launching some tests
+ * \section unittest-launch-some Launching some tests
  *
  *  If only some of the tests should be checked, then they have to be launched by
@@ -56 +52 @@
  *  libraries, which have not been installed so far, are found.
  *
- * \section Inspecting results
+ * \section unittest-results Inspecting results
  *
  *  Results of the test are shown during run. An \a Ok(2) indicates that
  *  two tests for the single launched testsuite passed.
  *
+ * \section unittest-add Adding new tests
+ *
+ *  \attention Name convention of files, (no spaces, use CamelCase) e.g.
+ *  \b AnalysisBondsUnitTest
+ *  - the unit test module should be called as follows:
+ *    -# either the name of the component or the module
+ *    -# followed by UnitTest.
+ *  - the test class should be called as follows:
+ *    -# the name of the class it tests
+ *    -# followed by Test.
+ *
+ *  Adding a new test is as easy as this:
+ *  -# Create a new module for declaration and definition of the unit test
+ *    in a suitable \b unittests subfolder (see above on policy and naming).
+ *    Check out one of the present unit tests and rename, but beware of
+ *    copy&paste errors!
+ *  -# Add the test to the \b Makefile.am contained in \b unittests.
+ *
+ *  If there is not yet a \b unittests folder:
+ *  -# Create a new \b Makefile.am, check out one of the present ones to get
+ *    an idea, below is a small list of contained elements. Note that the
+ *    variable must begin with a unique name as all Makefile.am on unit tests
+ *    are included into one big Makefile.am in \b src/unittests.
+ *  -# Add your ...SOURCES and ...HEADERS to TESTSOURCES and TESTHEADERS.
+ *  -# Add an include directive to \b src/unittests/Makefile.am of this
+ *    newly created \b Makefile.am.
+ *
+ *  What's contained in the \b Makefile.am:
+ *  -# ...SOURCES and ...HEADERS gathering all source and header files in this
+ *    \b unittests folder (this is needed for the test program that contains
+ *    all unit test in one executable).
+ *  -# ...TESTS gathering all test programs in this \b unittests folder.
+ *  -# ...TESTS is added to TESTS, check_PROGRAMS, noinst_PROGRAMS such that
+ *    it is known that they are just tests, programs for \a make \a check and
+ *    are not to be installed.
+ *  -# ...LIBS gathers general libs that all of the tests in this \b unittests
+ *    folder share.
+ *  -# for each unit test:
+ *    -# ...SOURCES gathers all source files that are required for the test.
+ *    -# ...LDADD gathers all libs that are required for compilation.
+ *
+ *
+ * \date 2011-10-31
+ *
  */