Fix more Doxygen warnings.
authorTeemu Murtola <teemu.murtola@gmail.com>
Wed, 21 Mar 2012 19:57:39 +0000 (21:57 +0200)
committerTeemu Murtola <teemu.murtola@gmail.com>
Mon, 26 Mar 2012 04:53:18 +0000 (07:53 +0300)
- Add documentation for some partially documented classes.
- Some fixes to cosmetic issues in surrounding code that were noticed.
- Some other clean-up.

There are a few warnings in pre-5.0 C code that are not addressed here.
Of the remaining warnings, quite a few are are either in obsolete code
(template.c, displacement.c), or in code that should be heavily
refactored (nbsearch.h, issue #866).

Change-Id: I7c309153769f35e93c4d0ff28667663e6a9e8ee3

27 files changed:
src/gromacs/analysisdata/modules/plot.h
src/gromacs/fatalerror.h
src/gromacs/options/basicoptioninfo.h
src/gromacs/options/basicoptionstorage.h
src/gromacs/options/optionflags.h
src/gromacs/options/optioninfo.h
src/gromacs/options/optionsvisitor.cpp
src/gromacs/options/timeunitmanager.h
src/gromacs/selection/evaluate.cpp
src/gromacs/selection/poscalc.cpp
src/gromacs/selection/selection.h
src/gromacs/selection/selectioncollection-impl.h
src/gromacs/selection/selectionenums.h
src/gromacs/selection/selectionoption.cpp
src/gromacs/selection/selectionoption.h
src/gromacs/selection/selectionoptioninfo.h
src/gromacs/selection/selectionoptionstorage.h
src/gromacs/selection/sm_keywords.cpp
src/gromacs/trajectoryanalysis/analysismodule-impl.h
src/gromacs/trajectoryanalysis/analysissettings-impl.h
src/gromacs/trajectoryanalysis/analysissettings.h
src/gromacs/trajectoryanalysis/modules/select.cpp
src/gromacs/trajectoryanalysis/runnercommon.h
src/gromacs/utility/arrayref.h
src/gromacs/utility/common.h
src/programs/mdrun/openmm_wrapper.cpp
src/testutils/datapath.h

index 235dfc0daed224aa3532ded2a59246f2f73a4007..a0b2a03793dc6f9e30e1671d82b37f2fdafb3370 100644 (file)
@@ -218,10 +218,21 @@ class AbstractPlotModule : public AnalysisDataModuleInterface
     protected:
         /*! \cond libapi */
         AbstractPlotModule();
-        //! Creates AbstractPlotModule and assign common settings for the plotting
+        //! Creates AbstractPlotModule and assign common settings.
         explicit AbstractPlotModule(const AnalysisDataPlotSettings &settings);
 
+        //! Whether an output file has been opened.
         bool isFileOpen() const;
+        /*! \brief
+         * Appends a single value to the current output line.
+         *
+         * \param[in] value  Value to append.
+         *
+         * Should be used from pointsAdded() implementations in derived classes
+         * to write out individual y values to the output.
+         *
+         * Must not be called if isFileOpen() returns false.
+         */
         void writeValue(real value) const;
         //! \endcond
 
@@ -244,7 +255,7 @@ class AnalysisDataPlotModule : public AbstractPlotModule
 {
     public:
         AnalysisDataPlotModule();
-        //! Creates AnalysisDataPlotModule and assign common settings for the plotting
+        //! Creates AnalysisDataPlotModule and assign common settings.
         explicit AnalysisDataPlotModule(const AnalysisDataPlotSettings &settings);
 
         virtual void pointsAdded(const AnalysisDataPointSetRef &points);
@@ -265,7 +276,7 @@ class AnalysisDataVectorPlotModule : public AbstractPlotModule
 {
     public:
         AnalysisDataVectorPlotModule();
-        //! Creates AnalysisDataVectorPlotModule and assign common settings for the plotting
+        //! Creates AnalysisDataVectorPlotModule and assign common settings.
         explicit AnalysisDataVectorPlotModule(const AnalysisDataPlotSettings &settings);
 
         /*! \brief
index ca611c30d78531bd0bf7a7f68b176872fe85974e..6e1fd11cb11d031037da3961ea8656a885366433 100644 (file)
@@ -42,7 +42,7 @@
  * Use of error return codes should be avoided in new code except in C wrappers
  * and similar, but for compatibility, facilities for handling them are
  * provided by the errorcodes.h header file.  It provides a set of error codes
- * (the enum ::ErrorCode) that should be used for return codes in functions.
+ * (the enum \ref gmx::ErrorCode) that should be used for return codes in functions.
  * It also provides macros ::GMX_ERROR and ::GMX_ERROR_NORET that should be
  * used for returning an error code.  setFatalErrorHandler() is provided to
  * alter the behavior of ::GMX_ERROR and ::GMX_ERROR_NORET.  The default
index 6ff9c7d4a521e894c8f8e5b86940dfb78195598f..fbf9ee27135ca20817271a3eacbaea1369750e3d 100644 (file)
@@ -62,6 +62,7 @@ class FileNameOptionStorage;
 class BooleanOptionInfo : public OptionInfo
 {
     public:
+        //! Creates an option info object for the given option.
         explicit BooleanOptionInfo(BooleanOptionStorage *option);
 };
 
@@ -73,6 +74,7 @@ class BooleanOptionInfo : public OptionInfo
 class IntegerOptionInfo : public OptionInfo
 {
     public:
+        //! Creates an option info object for the given option.
         explicit IntegerOptionInfo(IntegerOptionStorage *option);
 };
 
@@ -84,9 +86,10 @@ class IntegerOptionInfo : public OptionInfo
 class DoubleOptionInfo : public OptionInfo
 {
     public:
+        //! Creates an option info object for the given option.
         explicit DoubleOptionInfo(DoubleOptionStorage *option);
 
-        //! Whether the option provides a time value.
+        //! Whether the option specifies a time value.
         bool isTime() const;
 
         /*! \brief
@@ -112,6 +115,7 @@ class DoubleOptionInfo : public OptionInfo
 class StringOptionInfo : public OptionInfo
 {
     public:
+        //! Creates an option info object for the given option.
         explicit StringOptionInfo(StringOptionStorage *option);
 };
 
@@ -123,11 +127,20 @@ class StringOptionInfo : public OptionInfo
 class FileNameOptionInfo : public OptionInfo
 {
     public:
+        //! Creates an option info object for the given option.
         explicit FileNameOptionInfo(FileNameOptionStorage *option);
 
+        //! Whether the option specifies an input file.
         bool isInputFile() const;
+        //! Whether the option specifies an output file.
         bool isOutputFile() const;
+        //! Whether the option specifies a file used for both input and output.
         bool isInputOutputFile() const;
+        /*! \brief
+         * Whether the option specifies a library file.
+         *
+         * \see FileNameOption::libraryFile()
+         */
         bool isLibraryFile() const;
 
     private:
index c51a650c0a5093171ca6a1a9b1ebedde0aa445e9..43ed4d512e40ae04e9434e5bffa98e5e938bbd77 100644 (file)
@@ -122,7 +122,9 @@ class DoubleOptionStorage : public OptionStorageTemplate<double>
         virtual const char *typeString() const;
         virtual std::string formatValue(int i) const;
 
+        //! \copydoc DoubleOptionInfo::isTime()
         bool isTime() const { return bTime_; }
+        //! \copydoc DoubleOptionInfo::setScaleFactor()
         void setScaleFactor(double factor);
 
     private:
@@ -170,9 +172,13 @@ class FileNameOptionStorage : public OptionStorageTemplate<std::string>
         virtual const char *typeString() const { return "file"; }
         virtual std::string formatValue(int i) const;
 
+        //! \copydoc FileNameOptionInfo::isInputFile()
         bool isInputFile() const { return bRead_ && !bWrite_; }
+        //! \copydoc FileNameOptionInfo::isOutputFile()
         bool isOutputFile() const { return !bRead_ && bWrite_; }
+        //! \copydoc FileNameOptionInfo::isInputOutputFile()
         bool isInputOutputFile() const { return bRead_ && bWrite_; }
+        //! \copydoc FileNameOptionInfo::isLibraryFile()
         bool isLibraryFile() const { return bLibrary_; }
 
     private:
index 83fb51c2bf2bbdb4da1e3d10600be0934ebb5ae8..7de2de50e757481cc4a095e2b824d071be55bfa0 100644 (file)
@@ -47,7 +47,8 @@
 namespace gmx
 {
 
-/*! \internal \brief
+/*! \cond libapi */
+/*! \libinternal \brief
  * Flags for options.
  *
  * These flags are not part of the public interface, even though they are in an
@@ -102,8 +103,9 @@ enum OptionFlag
     //efAtomVal             = 1<<21,
 };
 
-//! Holds a combination of ::OptionFlag values.
+//! \libinternal Holds a combination of ::OptionFlag values.
 typedef FlagsTemplate<OptionFlag> OptionFlags;
+//! \endcond
 
 } // namespace gmx
 
index ecc2ec7fa7d15cdc10b5593b76b050242ad84c81..a913b9280c6e9e5fe95c6a08376304844dc686a8 100644 (file)
@@ -118,13 +118,17 @@ class OptionInfo
         std::string formatValues() const;
 
     protected:
+        /*! \cond libapi */
         /*! \brief
          * Wraps a given option object.
          */
         explicit OptionInfo(AbstractOptionStorage *option);
 
+        //! Returns the wrapped option storage object.
         AbstractOptionStorage &option() { return _option; }
+        //! Returns the wrapped option storage object.
         const AbstractOptionStorage &option() const { return _option; }
+        //! \endcond
 
     private:
         //! The wrapped option.
index 37688bc10bc4f83e97c799bb3d1a9d64fdb39f3c..7dc0429c002af687d8cdc90bc9dde0314c9c154b 100644 (file)
@@ -50,10 +50,12 @@ namespace gmx
  * OptionInfo
  */
 
+/*! \cond libapi */
 OptionInfo::OptionInfo(AbstractOptionStorage *option)
     : _option(*option)
 {
 }
+//! \endcond
 
 OptionInfo::~OptionInfo()
 {
index 53b08690b08087bbd7f7bcc02aabe7cb3256bec1..181158a243fb7066d7ab07aa49e7f7857e37747a 100644 (file)
@@ -50,7 +50,7 @@ class Options;
  * Time values for TimeUnitManager.
  *
  * \if internal
- * Currently, this should match with the ::time_unit_t enum defined in oenv.h
+ * Currently, this should match with the time_unit_t enum defined in oenv.h
  * except that there is no NULL first item in this enum.
  * \endif
  *
index 83567fa30ef3989d616776be55677e1200fe0738..baf1a2e8d06233ecf413d68c586bed0bcc379fb3 100644 (file)
 #include "selectioncollection-impl.h"
 #include "selelem.h"
 
+namespace
+{
+
 /*! \internal \brief
  * Reserves memory for a selection element from the evaluation memory pool.
+ *
+ * This class implements RAII semantics for allocating memory for selection
+ * element values from a selection evaluation memory pool.
+ *
+ * \ingroup module_selection
  */
 class MempoolSelelemReserver
 {
     public:
+        //! Constructs a reserver without initial reservation.
         MempoolSelelemReserver() : sel_(NULL) {}
+        /*! \brief
+         * Constructs a reserver with initial reservation.
+         *
+         * \param[in,out] sel    Selection element for which to reserve.
+         * \param[in]     count  Number of values to reserve.
+         *
+         * \see reserve()
+         */
         MempoolSelelemReserver(t_selelem *sel, int count)
             : sel_(NULL)
         {
             reserve(sel, count);
         }
+        //! Frees any memory allocated using this reserver.
         ~MempoolSelelemReserver()
         {
             if (sel_ != NULL)
@@ -88,6 +106,17 @@ class MempoolSelelemReserver
             }
         }
 
+        /*! \brief
+         * Reserves memory for selection element values using this reserver.
+         *
+         * \param[in,out] sel    Selection element for which to reserve.
+         * \param[in]     count  Number of values to reserve.
+         *
+         * Allocates space to store \p count output values in \p sel from the
+         * memory pool associated with \p sel, or from the heap if there is no
+         * memory pool.  Type of values to allocate is automatically determined
+         * from \p sel.
+         */
         void reserve(t_selelem *sel, int count)
         {
             GMX_RELEASE_ASSERT(sel_ == NULL, "Can only reserve one element with one instance");
@@ -101,14 +130,25 @@ class MempoolSelelemReserver
 
 /*! \internal \brief
  * Reserves memory for an index group from the evaluation memory pool.
+ *
+ * This class implements RAII semantics for allocating memory for an index
+ * group from a selection evaluation memory pool.
+ *
+ * \ingroup module_selection
  */
 class MempoolGroupReserver
 {
     public:
+        /*! \brief
+         * Creates a reserver associated with a given memory pool.
+         *
+         * \param    mp  Memory pool from which to reserve memory.
+         */
         explicit MempoolGroupReserver(gmx_sel_mempool_t *mp)
             : mp_(mp), g_(NULL)
         {
         }
+        //! Frees any memory allocated using this reserver.
         ~MempoolGroupReserver()
         {
             if (g_ != NULL)
@@ -117,6 +157,15 @@ class MempoolGroupReserver
             }
         }
 
+        /*! \brief
+         * Reserves memory for an index group using this reserver.
+         *
+         * \param[in,out] g      Index group to reserve.
+         * \param[in]     count  Number of atoms to reserve space for.
+         *
+         * Allocates memory from the memory pool to store \p count atoms in
+         * \p g.
+         */
         void reserve(gmx_ana_index_t *g, int count)
         {
             GMX_RELEASE_ASSERT(g_ == NULL, "Can only reserve one element with one instance");
@@ -131,19 +180,34 @@ class MempoolGroupReserver
 
 /*! \internal \brief
  * Assigns a temporary value for a selection element.
+ *
+ * This class implements RAII semantics for temporarily assigning the value
+ * pointer of a selection element to point to a different location.
+ *
+ * \ingroup module_selection
  */
 class SelelemTemporaryValueAssigner
 {
     public:
+        //! Constructs an assigner without an initial assignment.
         SelelemTemporaryValueAssigner()
             : sel_(NULL), old_ptr_(NULL), old_nalloc_(0)
         {
         }
+        /*! \brief
+         * Constructs an assigner with an initial assignment.
+         *
+         * \param[in,out] sel     Selection element for which to assign.
+         * \param[in]     vsource Element to which \p sel values will point to.
+         *
+         * \see assign()
+         */
         SelelemTemporaryValueAssigner(t_selelem *sel, t_selelem *vsource)
             : sel_(NULL)
         {
             assign(sel, vsource);
         }
+        //! Undoes any temporary assignment done using this assigner.
         ~SelelemTemporaryValueAssigner()
         {
             if (sel_ != NULL)
@@ -152,9 +216,22 @@ class SelelemTemporaryValueAssigner
             }
         }
 
+        /*! \brief
+         * Assigns a temporary value pointer.
+         *
+         * \param[in,out] sel     Selection element for which to assign.
+         * \param[in]     vsource Element to which \p sel values will point to.
+         *
+         * Assigns the value pointer in \p sel to point to the values in
+         * \p vsource, i.e., any access/modification to values in \p sel
+         * actually accesses values in \p vsource.
+         */
         void assign(t_selelem *sel, t_selelem *vsource)
         {
-            GMX_RELEASE_ASSERT(sel_ == NULL, "Can only assign one element with one instance");
+            GMX_RELEASE_ASSERT(sel_ == NULL,
+                               "Can only assign one element with one instance");
+            GMX_RELEASE_ASSERT(sel->v.type == vsource->v.type,
+                               "Mismatching selection value types");
             old_ptr_ = sel->v.u.ptr;
             old_nalloc_ = sel->v.nalloc;
             _gmx_selvalue_setstore(&sel->v, vsource->v.u.ptr);
@@ -167,6 +244,8 @@ class SelelemTemporaryValueAssigner
         int                     old_nalloc_;
 };
 
+} // namespace
+
 /*!
  * \param[in] fp       File handle to receive the output.
  * \param[in] evalfunc Function pointer to print.
index d7889d5610023b98d6e01f485b5df6cb850defc1..0d4aed700e2efe4174df93993f03da4aa1e11b05 100644 (file)
@@ -227,7 +227,7 @@ static const char *const poscalc_enum_strings[] = {
     "dyn_mol_com",   "dyn_mol_cog",
     NULL,
 };
-//! Number of elements in ::poscalc_enum_strings.
+//! Number of elements in poscalc_enum_strings.
 #define NENUM asize(poscalc_enum_strings)
 
 /*! \brief
index 267f66807167138946d9785d4e9b59cff32715f8..45a5ae86a13867e21b3614336021f9e507376a4c 100644 (file)
@@ -128,6 +128,7 @@ class Selection
         //! Deprecated method for direct access to atom index data.
         gmx_ana_index_t *indexGroup() const { return rawPositions_.g; }
 
+        // TODO: Remove direct access to the flags from the public interface.
         //! Returns true if the given flag is set.
         bool hasFlag(SelectionFlag flag) const { return flags_.test(flag); }
         //! Sets the flags for this selection.
@@ -278,6 +279,12 @@ class SelectionPosition
 {
     public:
         /*! \brief
+         * Constructs a wrapper object for given selection position.
+         *
+         * \param[in] sel    Selection from which the position is wrapped.
+         * \param[in] index  Zero-based index of the position to wrap.
+         *
+         * Does not throw.  Asserts if \p index is out of range.
          */
         SelectionPosition(const Selection *sel, int index)
             : sel_(sel), i_(index)
@@ -367,17 +374,17 @@ class SelectionPosition
          * across frames.  After compilation, these IDs are consequently
          * numbered starting from zero.  For each frame, the ID then reflects
          * the location of the position in the original array of positions.
-         * If ::efDynamicMask has been set for the parent selection, the IDs
-         * for positions not present in the current selection are set to
-         * -1, otherwise they are removed completely.
+         * If SelectionOption::dynamicMask() has been set for the parent
+         * selection, the IDs for positions not present in the current
+         * selection are set to -1, otherwise they are removed completely.
          *
          * Example:
          * If a dynamic selection consists of three positions, after
          * compilation refId() will return 0, 1, 2 for them, respectively.
          * If for a particular frame, only the first and the third are present,
          * refId() will return 0, 2.
-         * If ::efDynamicMask has been set, all three positions can be accessed
-         * also in this case and refId() will return 0, -1, 2.
+         * If SelectionOption::dynamicMask() has been set, all three positions
+         * can be accessed also in this case and refId() will return 0, -1, 2.
          */
         int refId() const
         {
index 4e1c522c70288d0fda6bb700169be1ce3643a301..4121f1deae1cf027918b1e7714adc3c9ab73cfc5 100644 (file)
 
 #include "../legacyheaders/typedefs.h"
 
-#include "gromacs/utility/uniqueptr.h"
-
 #include "../options/options.h"
 #include "../utility/flags.h"
+#include "../utility/uniqueptr.h"
 #include "indexutil.h"
 #include "selectioncollection.h"
 
@@ -113,6 +112,11 @@ class SelectionCollection::Impl
             {
             }
 
+            /*! \brief
+             * Returns the number of selections requested in this request.
+             *
+             * -1 indicates no upper limit.
+             */
             int count() const;
 
             std::string                 name;
@@ -169,9 +173,30 @@ class SelectionCollection::Impl
          */
         void runParser(void *scanner, int maxnr,
                        std::vector<Selection *> *output);
+        /*! \brief
+         * Adds a selection request for delayed user input.
+         *
+         * \param[in] name    Name for the requested selections.
+         * \param[in] descr   Description of the requested selections.
+         * \param     storage Storage object to receive the selections.
+         *
+         * \see parseRequestedFromStdin()
+         */
         void requestSelections(const std::string &name,
                                const std::string &descr,
                                SelectionOptionStorage *storage);
+        /*! \brief
+         * Replace group references by group contents.
+         *
+         * \param[in]    root    Root of selection tree to process.
+         * \param        errors  Object for reporting any error messages.
+         *
+         * Recursively searches the selection tree for unresolved external
+         * references.  If one is found, finds the referenced group in
+         * \a _grps and replaces the reference with a constant element that
+         * contains the atoms from the referenced group.  Any failures to
+         * resolve references are reported to \p errors.
+         */
         void resolveExternalGroups(struct t_selelem *root,
                                    MessageStringCollector *errors);
 
index cdbd201b0cb6190c9745348a57fd63adbbd682a2..4ef8ca5f9ea9cfcb43488f913cdf464b1b2b8dfd 100644 (file)
@@ -54,7 +54,8 @@ typedef enum
 namespace gmx
 {
 
-/*! \brief
+/*! \cond internal */
+/*! \internal \brief
  * Flags for options.
  *
  * These flags are not part of the public interface, even though they are in an
@@ -73,8 +74,9 @@ enum SelectionFlag
     efEvaluateForces            = 1<<6,
 };
 
-//! Holds a collection of ::SelectionFlag values.
+//! \internal Holds a collection of ::SelectionFlag values.
 typedef FlagsTemplate<SelectionFlag> SelectionFlags;
+//! \endcond
 
 }
 
index cac7113a1b84c64aecdbff420439d9aa142e0e09..9dc9e786ea5cf1336ba2ab626fcd8d44e5a318ef 100644 (file)
@@ -293,10 +293,12 @@ class SelectionCollectionSetter : public OptionsModifyingTypeVisitor<SelectionOp
 
 } // namespace
 
+/*! \cond libapi */
 void setSelectionCollectionForOptions(Options *options,
                                       SelectionCollection *selections)
 {
     SelectionCollectionSetter(selections).visitSubSection(options);
 }
+//! \endcond
 
 } // namespace gmx
index 675911d19281dc2e35691b3159bbfaabc2cd8e54..d84ea4e41fe1d1fc37b263ccbf54fdc2de1e4755 100644 (file)
@@ -88,7 +88,9 @@ class SelectionOption : public OptionTemplate<Selection *, SelectionOption>
         /*! \brief
          * Handle dynamic selections for this option with position masks.
          *
+         * \if internal
          * Sets ::POS_MASKONLY on the positions for this selection.
+         * \endif
          */
         MyClass &dynamicMask()
         { _selectionFlags.set(efDynamicMask); return me(); }
index 8896829de84dfa349761956d3914db64b9a72229..7b9729a356a965111981a5e9ef20efa3bab14cb4 100644 (file)
@@ -134,6 +134,7 @@ class SelectionOptionInfo : public OptionInfo
         const SelectionOptionStorage &option() const;
 };
 
+/*! \cond libapi */
 /*! \libinternal \brief
  * Set selection collection for all selection options.
  *
@@ -147,6 +148,7 @@ class SelectionOptionInfo : public OptionInfo
  */
 void setSelectionCollectionForOptions(Options *options,
                                       SelectionCollection *selections);
+//! \endcond
 
 } // namespace gmx
 
index b42284d9dd478eaa2cdd3f2bf97540a178a9e771..eeb1b0755f5f543fdca654af070f5584778a8da7 100644 (file)
@@ -68,6 +68,7 @@ class SelectionOptionStorage : public OptionStorageTemplate<Selection *>
         virtual const char *typeString() const { return "sel"; }
         virtual std::string formatValue(int i) const;
 
+        //! \copydoc SelectionOptionInfo::setSelectionCollection()
         void setSelectionCollection(SelectionCollection *selections)
         {
             _sc = selections;
index 08f3b36ad7ec1df967fc377bb7693088004c9c8b..e936be3bba387620153cc3e637dbaa9ea8a8b8dd 100644 (file)
@@ -159,6 +159,7 @@ typedef struct t_methoddata_kwstr
             char      *s;
         }              u;
     }                 *m;
+    /**< Array of strings/regular expressions to match against.*/
 } t_methoddata_kwstr;
 
 /** Parameters for integer keyword evaluation. */
index 00857d0440ccd0cb54216b5c567fa5447b463b80..0d0f4973f6f89aee155d066de51d02863e2007e1 100644 (file)
@@ -89,6 +89,13 @@ class TrajectoryAnalysisModule::Impl
 class TrajectoryAnalysisModuleDataBasic : public TrajectoryAnalysisModuleData
 {
     public:
+        /*! \brief
+         * Initializes thread-local storage for data handles and selections.
+         *
+         * \param[in] module     Analysis module to use for data objects.
+         * \param[in] opt        Data parallelization options.
+         * \param[in] selections Thread-local selection collection.
+         */
         TrajectoryAnalysisModuleDataBasic(TrajectoryAnalysisModule *module,
                                           const AnalysisDataParallelOptions &opt,
                                           const SelectionCollection &selections);
index 1ff47e511ba877c367232c9f5eb7731ab97fe6fe..680df664e1bb45983a0661274fd4f4cb77952907 100644 (file)
@@ -57,12 +57,18 @@ class TrajectoryAnalysisSettings::Impl
         //! Initializes the default values for the settings object.
         Impl() : flags(0), frflags(0), bRmPBC(true), bPBC(true) {}
 
+        //! Global time unit setting for the analysis module.
         TimeUnitManager      timeUnitManager;
+        //! Global plotting settings for the analysis module.
         AnalysisDataPlotSettings plotSettings;
+        //! Flags for the analysis module.
         unsigned long        flags;
+        //! Frame reading flags for the analysis module.
         int                  frflags;
 
+        //! Whether to make molecules whole for each frame.
         bool                 bRmPBC;
+        //! Whether to pass PBC information to the analysis module.
         bool                 bPBC;
 };
 
index 1840caaed97f65d49207d8e82ee2cc0474b6d79e..7c116e8e4a0426cf2116374b2dfef80c8a4d4275 100644 (file)
@@ -163,7 +163,7 @@ class TrajectoryAnalysisSettings
          *
          * If called in TrajectoryAnalysisModule::initOptions(), this function
          * sets the default for whether PBC are used in the analysis.
-         * If ::efNoUserPBC is not set, a command-line option is provided
+         * If \ref efNoUserPBC is not set, a command-line option is provided
          * for the user to override the default value.
          * If called later, it overrides the setting provided by the user or an
          * earlier call.
@@ -174,7 +174,7 @@ class TrajectoryAnalysisSettings
          * TrajectoryAnalysisModule::analyzeFrame() is NULL.
          * The value of the flag can also be accessed with hasPBC().
          *
-         * \see ::efNoUserPBC
+         * \see efNoUserPBC
          */
         void setPBC(bool bPBC);
         /*! \brief
@@ -184,7 +184,7 @@ class TrajectoryAnalysisSettings
          *
          * If called in TrajectoryAnalysisModule::initOptions(), this function
          * sets the default for whether molecules are made whole.
-         * If ::efNoUserRmPBC is not set, a command-line option is provided
+         * If \ref efNoUserRmPBC is not set, a command-line option is provided
          * for the user to override the default value.
          * If called later, it overrides the setting provided by the user or an
          * earlier call.
@@ -195,11 +195,11 @@ class TrajectoryAnalysisSettings
          * The main use of this function is to call it with \c false if your
          * analysis program does not require whole molecules as this can
          * increase the performance.
-         * In such a case, you can also specify ::efNoUserRmPBC to not to
+         * In such a case, you can also specify \ref efNoUserRmPBC to not to
          * confuse the user with an option that would only slow the program
          * down.
          *
-         * \see ::efNoUserRmPBC
+         * \see efNoUserRmPBC
          */
         void setRmPBC(bool bRmPBC);
         /*! \brief
index 2a0ce2b28600907d308a42e2f0bc135797cb5c44..46a9b34151533ed048b9bacd2307b31572750ccf 100644 (file)
@@ -67,6 +67,9 @@ namespace gmx
 namespace analysismodules
 {
 
+namespace
+{
+
 /*! \internal \brief
  * Data module for writing index files.
  *
@@ -78,6 +81,7 @@ class IndexFileWriterModule : public AnalysisDataModuleInterface
         IndexFileWriterModule();
         virtual ~IndexFileWriterModule();
 
+        //! Sets the file name to write the index file to.
         void setFileName(const std::string &fnm);
         void addGroup(const std::string &name, bool bDynamic);
 
@@ -228,6 +232,8 @@ void IndexFileWriterModule::dataFinished()
     closeFile();
 }
 
+} // namespace
+
 
 /********************************************************************
  * Select::ModuleData
index 4a1cf53eada5e2b5d06a6b0df8e608211d32f585..a2c4de47889b570181c753a17562c68504cdf7bc 100644 (file)
@@ -64,24 +64,56 @@ class TrajectoryAnalysisRunnerCommon
          */
         enum HelpFlag
         {
-            efHelpShowOptions           = 1<<0,
-            efHelpShowHidden            = 1<<1,
-            efHelpShowDescriptions      = 1<<2,
+            efHelpShowOptions           = 1<<0, //!< Show options.
+            efHelpShowHidden            = 1<<1, //!< Show hidden options.
+            efHelpShowDescriptions      = 1<<2  //!< Show detailed description.
         };
-        //! Combination of ::HelpFlag values.
+        //! Combination of \ref HelpFlag values.
         typedef unsigned long HelpFlags;
 
+        /*! \brief
+         * Initializes a new runner helper.
+         *
+         * \param    settings  Settings object to use.
+         */
         explicit TrajectoryAnalysisRunnerCommon(TrajectoryAnalysisSettings *settings);
         ~TrajectoryAnalysisRunnerCommon();
 
+        //! Initializes common options for trajectory analysis.
         Options &initOptions();
+        //! Scales time option values according to the time unit set.
         void scaleTimeOptions(Options *options);
+        /*! \brief
+         * Processes common option values after they have been parsed.
+         *
+         * \returns false if the tool should exit after printing help.
+         */
         bool initOptionsDone();
+        //! Initialize index groups for selections.
         void initIndexGroups(SelectionCollection *selections);
+        //! Free memory allocated for index groups.
         void doneIndexGroups(SelectionCollection *selections);
+        //! Load topology information if provided and/or required.
         void initTopology(SelectionCollection *selections);
+        /*! \brief
+         * Reads the first frame from the trajectory.
+         *
+         * After this call, frame() returns the first frame.
+         */
         void initFirstFrame();
+        /*! \brief
+         * Reads the next frame from the trajectory.
+         *
+         * \returns false if there were no more frames.
+         *
+         * After this call, frame() returns the newly loaded frame.
+         */
         bool readNextFrame();
+        /*! \brief
+         * Performs common initialization for the currently loaded frame.
+         *
+         * Currently, makes molecules whole if requested.
+         */
         void initFrame();
 
         //! Returns flags for help printing.
index 758515d54550c690885e841c7c0f984db62c9f6e..f232f072fe0335b86c9698f9065b3fe91a8453c4 100644 (file)
@@ -73,11 +73,17 @@ template <typename T>
 class ConstArrayRef
 {
     public:
+        //! Type of values stored in the container.
         typedef T         value_type;
+        //! Type for representing size of the container.
         typedef size_t    size_type;
+        //! Type for representing difference between two container indices.
         typedef ptrdiff_t difference_type;
+        //! Const reference to a container element.
         typedef const T  &const_reference;
+        //! Const pointer to a container element.
         typedef const T  *const_pointer;
+        //! Const iterator type for the container.
         typedef const T  *const_iterator;
         //! Equal to \a const_reference since changes are not allowed.
         typedef const_reference reference;
@@ -137,16 +143,25 @@ class ConstArrayRef
         {
         }
 
+        //! Returns an interator to the beginning of the container.
         const_iterator begin() const { return begin_; }
+        //! Returns an interator to the end of the container.
         const_iterator end() const { return end_; }
+        //! Returns an interator to the reverse beginning of the container.
         const_iterator rbegin() const { return reverse_iterator(end()); }
+        //! Returns an interator to the reverse end of the container.
         const_iterator rend() const { return reverse_iterator(begin()); }
 
+        //! Returns the size of the container.
         size_type size() const { return end_ - begin_; }
+        //! Identical to size().
         size_type capacity() const { return end_ - begin_; }
+        //! Whether the container is empty.
         bool empty() const { return begin_ == end_; }
 
+        //! Access container element.
         const_reference operator[](size_type n) const { return begin_[n]; }
+        //! Access container element (throws on out-of-range error).
         const_reference at(size_type n) const
         {
             if (n >= size())
@@ -155,7 +170,9 @@ class ConstArrayRef
             }
             return begin_[n];
         }
+        //! Returns the first element in the container.
         const_reference front() const { return *begin_; }
+        //! Returns the last element in the container.
         const_reference back() const { return *(end_ - 1); }
 
         /*! \brief
index 2e8cd87d9a23fdfb0d7aacc84bad0fedaa7ddd15..0936f2ec3febd9b4521497d7ef2446d221220b42 100644 (file)
@@ -45,6 +45,7 @@
 
 #include <boost/scoped_ptr.hpp>
 
+/*! \cond libapi */
 /*! \libinternal \brief
  * Macro to declare a class non-copyable and non-assignable.
  *
@@ -66,6 +67,7 @@
 #define GMX_DISALLOW_ASSIGN(ClassName) \
     private: \
         ClassName &operator =(const ClassName &)
+//! \endcond
 
 namespace gmx
 {
@@ -73,12 +75,15 @@ namespace gmx
 /*! \libinternal \brief
  * Helper class to manage a pointer to a private implementation class.
  *
- * This helper provides the following benefits (the first two could also be
+ * This helper provides the following benefits (all but the last could also be
  * achieved with boost::scoped_ptr):
  *  - Automatic memory management: the implementation pointer is freed in
  *    the destructor automatically.  If the destructor is not declared or is
  *    defined inline in the header file, a compilation error occurs instead
  *    of a memory leak or undefined behavior.
+ *  - Exception safety in constructors: the implementation pointer is freed
+ *    correctly even if the constructor of the containing class throws after
+ *    the implementation class is constructed.
  *  - Copy and/or assignment is automatically disallowed if explicit copy
  *    constructor and/or assignment operator is not provided.
  *  - Compiler helps to manage const-correctness: in const methods, it is not
@@ -125,12 +130,23 @@ class PrivateImplPointer
         explicit PrivateImplPointer(Impl *ptr) : ptr_(ptr) {}
         ~PrivateImplPointer() {}
 
+        /*! \brief
+         * Sets a new implementation class and destructs the previous one.
+         *
+         * Needed, e.g., to implement assignable classes.
+         */
         void reset(Impl *ptr) { ptr_.reset(ptr); }
+        //! Access the raw pointer.
         Impl *get() { return ptr_.get(); }
+        //! Access the implementation class as with a raw pointer.
         Impl *operator->() { return ptr_.get(); }
+        //! Access the implementation class as with a raw pointer.
         Impl &operator*() { return *ptr_; }
+        //! Access the raw pointer.
         const Impl *get() const { return ptr_.get(); }
+        //! Access the implementation class as with a raw pointer.
         const Impl *operator->() const { return ptr_.get(); }
+        //! Access the implementation class as with a raw pointer.
         const Impl &operator*() const { return *ptr_; }
 
     private:
index d7a01c4d3a1f66375e82f968465e7bab7e4a7a8d..a9ee28f19e7b009fa749a7b89ca8daa042bec710 100644 (file)
@@ -380,11 +380,11 @@ void GmxOpenMMPlatformOptions::print()
 class OpenMMData
 {
 public:
-    System* system;      /*! The system to simulate. */
-    Context* context;   /*! The OpenMM context in which the simulation is carried out. */
-    Integrator* integrator; /*! The integrator used in the simulation. */
-    gmx_bool removeCM;          /*! If \true remove venter of motion, false otherwise. */
-    GmxOpenMMPlatformOptions *platformOpt; /*! Platform options. */
+    System* system;      //!< The system to simulate.
+    Context* context;   //!< The OpenMM context in which the simulation is carried out.
+    Integrator* integrator; //!< The integrator used in the simulation.
+    gmx_bool removeCM;          //!< If true, remove center of mass motion, false otherwise.
+    GmxOpenMMPlatformOptions *platformOpt; //!< Platform options.
 };
 
 /*!
index daed0f92addf7659e6f4027a26dc74117d629367..8db826fb8883c531772bb87273fad45ee67fed74 100644 (file)
@@ -40,7 +40,7 @@
  * \inlibraryapi
  * \ingroup module_testutils
  */
-/*! \defgroup module_testutils Unit Testing Utility Modules
+/*! \libinternal \defgroup module_testutils Unit Testing Utility Modules
  * \brief
  * Common helper classes and functions for writing unit tests.
  *
@@ -97,8 +97,6 @@ const char *getTestDataPath();
  */
 void setTestDataPath(const char *path);
 
-/*!\}*/
-
 } // namespace test
 } // namespace gmx