Sort all includes in src/gromacs

[alexxy/gromacs.git] / src / gromacs / options.h

diff --git a/src/gromacs/options.h b/src/gromacs/options.h
index 1e2d48292a613a6f1969596481726ad0bee1c9d2..a6bc7e8362f7b94f4c5fa3077638f096e2411317 100644 (file)
--- a/src/gromacs/options.h
+++ b/src/gromacs/options.h
@@ -1,10 +1,10 @@
 /*
  * This file is part of the GROMACS molecular simulation package.
  *
- * Copyright (c) 2010,2011,2012, by the GROMACS development team, led by
- * David van der Spoel, Berk Hess, Erik Lindahl, and including many
- * others, as listed in the AUTHORS file in the top-level source
- * directory and at http://www.gromacs.org.
+ * Copyright (c) 2010,2011,2012,2013,2014, by the GROMACS development team, led by
+ * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
+ * and including many others, as listed in the AUTHORS file in the
+ * top-level source directory and at http://www.gromacs.org.
  *
  * GROMACS is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public License
@@ -32,7 +32,7 @@
  * To help us fund GROMACS development, we humbly ask that you cite
  * the research papers on the package. Check out http://www.gromacs.org.
  */
-/*! \defgroup module_options Extensible Handling of Options
+/*! \defgroup module_options Extensible Handling of Options (options)
  * \ingroup group_utilitymodules
  * \brief
  * Provides functionality for handling options.
@@ -46,6 +46,70 @@
  * descriptions for individual options as well as for the whole set of options.
  * These can then be used to write out help text.
  *
+ * The sequence charts below provides an overview of how the options work from
+ * usage perspective.  They include two fictional modules, A and B, that provide
+ * options, and a main routine that manages these.  The first chart shows a
+ * typical initialization sequence, where the main routine creates an options
+ * object, and calls an initOptions() method in each module that can provide
+ * options (the modules may also request their submodules to add their own
+ * options).  Each module uses gmx::Options::addOption() to add the options
+ * they require, and specify output variables into which the options values are
+ * stored.
+ * \msc
+ *     main,
+ *     options [ label="Options", URL="\ref gmx::Options" ],
+ *     A [ label="module A" ],
+ *     B [ label="module B" ];
+ *
+ *     main box B [ label="main owns all objects" ];
+ *     main => options [ label="create", URL="\ref gmx::Options::Options()" ];
+ *     main => A [ label="initOptions()" ];
+ *     A => options [ label="addOption()", URL="\ref gmx::Options::addOption()" ];
+ *     ...;
+ *     main << A;
+ *     main => B [ label="initOptions()" ];
+ *     B => options [ label="addOption()", URL="\ref gmx::Options::addOption()" ];
+ *     ...;
+ *     main << B;
+ * \endmsc
+ *
+ * After all options have been specified, they can be parsed.  A parser splits
+ * the input into option-value pairs (one option may have multiple values), and
+ * passes these into the gmx::Options object, which is responsible for
+ * converting them into the appropriate types and storing the values into the
+ * variables provided in the calls to gmx::Options::addOption().
+ * \msc
+ *     main,
+ *     parser [ label="parser" ],
+ *     options [ label="Options", URL="\ref gmx::Options" ],
+ *     A [ label="module A" ],
+ *     B [ label="module B" ];
+ *
+ *     main => parser [ label="parse()" ];
+ *     parser => options [ label="assign(string)" ];
+ *     options -> A [ label="set variable" ];
+ *     parser => options [ label="assign(string)" ];
+ *     options -> B [ label="set variable" ];
+ *     ...;
+ * \endmsc
+ *
+ * After all options have been parsed (possibly using multiple different
+ * parsers), gmx::Options::finish() is called.  This performs final
+ * validation of the options and may further adjust the values stored in the
+ * output variables (see documentation on individual option types on when this
+ * may happen).
+ * \msc
+ *     main,
+ *     options [ label="Options", URL="\ref gmx::Options" ],
+ *     A [ label="module A" ],
+ *     B [ label="module B" ];
+ *
+ *     main => options [ label="finish()", URL="\ref gmx::Options::finish()" ];
+ *     options -> A [ label="set variable" ];
+ *     options -> B [ label="set variable" ];
+ *     ...;
+ * \endmsc
+ *
  * Module \ref module_commandline implements classes that assign option values
  * from command line and produce help for programs that use the command line
  * parser.
@@ -82,8 +146,10 @@
 #ifndef GMX_OPTIONS_H
 #define GMX_OPTIONS_H
 
-#include "options/basicoptions.h"
-#include "options/filenameoption.h"
-#include "options/options.h"
+#include "gromacs/fileio/filenm.h"
+#include "gromacs/options/basicoptions.h"
+#include "gromacs/options/filenameoption.h"
+#include "gromacs/options/filenameoptionmanager.h"
+#include "gromacs/options/options.h"
 
 #endif