- Add missing documentation in partially documented classes.
- Add documentation for gmx::internal and gmx::test::internal
namespaces (the former adds some warnings outside the tests).
- Fix incorrect tag in paralleloptions.h (unrelated, fixes documentation
of the gmx namespace).
Change-Id: I14e94235307b3b6e6606bba0b8502b780043cab6
*
* For more info, check our website at http://www.gromacs.org
*/
-/*! \libinternal file
+/*! \libinternal \file
* \brief
* Declares gmx::AnalysisDataParallelOptions.
*
class AnalysisDataTestInputPointSet
{
public:
- AnalysisDataTestInputPointSet();
-
+ //! Returns the number of columns in the point set.
int size() const { return y_.size(); }
+ //! Returns the value in column \p i.
real y(int i) const { return y_[i]; }
+ //! Returns the error in column \p i.
real dy(int i) const { return 0.0; }
+ //! Returns whether the value in column \p i is present.
real present(int i) const { return true; }
+ //! Returns a vector of values for all columns.
const std::vector<real> &yvector() const { return y_; }
private:
+ //! Creates an empty point set.
+ AnalysisDataTestInputPointSet();
+
std::vector<real> y_;
friend class AnalysisDataTestInput;
class AnalysisDataTestInputFrame
{
public:
- AnalysisDataTestInputFrame(int index, real x);
-
- bool isMultipoint() const { return points_.size() > 1; }
-
+ //! Returns zero-based index for the frame.
int index() const { return index_; }
+ //! Returns x coordinate for the frame.
real x() const { return x_; }
+ //! Returns error in the x coordinate for the frame.
real dx() const { return 0.0; }
+ //! Number of individual point sets in the frame.
int pointSetCount() const { return points_.size(); }
+ //! Returns a point set object for a given point set.
const AnalysisDataTestInputPointSet &points(int index = 0) const
{
GMX_ASSERT(index >= 0 && static_cast<size_t>(index) < points_.size(),
}
private:
+ //! Constructs a new frame object with the given values.
+ AnalysisDataTestInputFrame(int index, real x);
+
int index_;
real x_;
std::vector<AnalysisDataTestInputPointSet> points_;
explicit AnalysisDataTestInput(const real *data);
~AnalysisDataTestInput();
+ //! Returns the number of frames in the input data.
int frameCount() const { return frames_.size(); }
+ //! Returns the number of columns in the input data.
int columnCount() const { return columnCount_; }
+ //! Whether the input data is multipoint.
bool isMultipoint() const { return bMultipoint_; }
+ //! Returns a frame object for the given input frame.
const AnalysisDataTestInputFrame &frame(int index) const;
private:
AbstractAnalysisData *source);
protected:
+ /*! \brief
+ * Reference data object used for the reference checker modules.
+ *
+ * Tests can use the data object also for their own purposes if needed.
+ */
gmx::test::TestReferenceData data_;
};
*
* \inpublicapi
*/
+/*! \namespace gmx::internal
+ * \brief
+ * Internal Gromacs namespace.
+ *
+ * This namespace is used to contain some implementation-specific functions and
+ * classes. These are not meant for direct user access, but typically reside
+ * in public headers because of implementation reasons.
+ */
*/
/*! \internal \file
* \brief Testing/debugging tool for the selection engine.
+ *
+ * \author Teemu Murtola <teemu.murtola@cbr.su.se>
*/
#ifdef HAVE_CONFIG_H
#include <config.h>
}
+/*! \internal \brief
+ * The main function for the selection testing tool.
+ */
int
main(int argc, char *argv[])
{
* \brief
* Functions for accessing test input files.
*
+ * Functions in this header provide methods to access data files that are
+ * located in the test source directory. This is typically used to provide
+ * input files for the tests.
+ *
* \author Teemu Murtola <teemu.murtola@cbr.su.se>
* \inlibraryapi
* \ingroup module_testutils
*/
+/*! \defgroup module_testutils Unit Testing Utility Modules
+ * \brief
+ * Common helper classes and functions for writing unit tests.
+ *
+ * \ingroup group_utilitymodules
+ */
#ifndef GMX_TESTUTILS_DATAPATH_H
#define GMX_TESTUTILS_DATAPATH_H
/*! \libinternal \brief
* Namespace for unit testing utilities.
*
+ * This namespace contains utilities that are shared between unit tests.
+ * Most members are declared in the \ref module_testutils module, but some
+ * are also declared within individual tests (these are typically candidates
+ * for using in other tests as well).
+ *
* \ingroup module_testutils
*/
namespace test
/*! \libinternal \brief
* Returns the path to a test input file.
*
+ * \param[in] filename Relative path/filename to a test input file.
+ * \returns Path to \p filename under the test input data directory.
+ *
* \inlibraryapi
*/
std::string getTestFilePath(const char *filename);
/*! \libinternal \brief
* Returns the path to the test input directory.
*
+ * \returns Path to input data directory for the test executable.
+ *
* \inlibraryapi
*/
const char *getTestDataPath();
/*! \libinternal \brief
* Sets the test input directory.
*
+ * \param[in] path Path from which test input data is looked up from.
+ *
+ * \p path must name an existing directory.
+ *
+ * This function is automatically called by test_main_gtest.cpp and
+ * test_main_gmock.cpp.
+ *
* \inlibraryapi
*/
void setTestDataPath(const char *path);
class TestReferenceData::Impl
{
public:
+ //! String constant for output XML version string.
static const xmlChar * const cXmlVersion;
+ //! String constant for XML stylesheet processing instruction name.
static const xmlChar * const cXmlStyleSheetNodeName;
+ //! String constant for XML stylesheet reference.
static const xmlChar * const cXmlStyleSheetContent;
+ //! String constant for naming the root XML element.
static const xmlChar * const cRootNodeName;
+ //! Initializes a checker in the given mode.
explicit Impl(ReferenceDataMode mode);
~Impl();
class TestReferenceChecker::Impl
{
public:
+ //! String constant for naming XML elements for boolean values.
static const xmlChar * const cBooleanNodeName;
+ //! String constant for naming XML elements for string values.
static const xmlChar * const cStringNodeName;
+ //! String constant for naming XML elements for integer values.
static const xmlChar * const cIntegerNodeName;
+ //! String constant for naming XML elements for floating-point values.
static const xmlChar * const cRealNodeName;
+ //! String constant for naming XML attribute for value identifiers.
static const xmlChar * const cIdAttrName;
+ //! String constant for naming compounds for vectors.
static const char * const cVectorType;
+ //! String constant for naming compounds for sequences.
static const char * const cSequenceType;
+ //! String constant for value identifier for sequence length.
static const char * const cSequenceLengthName;
//! Creates a checker that does nothing.
//! Returns the path of this checker with \p id appended.
std::string appendPath(const char *id) const;
+ /*! \brief
+ * Finds/creates a reference data node to match against.
+ *
+ * \param[in] name Type of node to find.
+ * \param[in] id Unique identifier of the node (can be NULL, in
+ * which case the next node without an id is matched).
+ * \returns Matching node, or NULL if no matching node found
+ * (NULL is never returned in write mode).
+ * \throws TestException if node creation fails in write mode.
+ *
+ * Searches for a node in the reference data that matches the given
+ * \p name and \p id. Searching starts from the node that follows the
+ * previously matched node (relevant for performance, and if there are
+ * duplicate ids or nodes without ids). If a match is not found, the
+ * method returns NULL in read mode and creates a new node in write
+ * mode. If the creation fails in write mode, throws.
+ */
xmlNodePtr findOrCreateNode(const xmlChar *name, const char *id);
+ /*! \brief
+ * Helper method for checking a reference data value.
+ *
+ * \param[in] name Type of node to find.
+ * \param[in] id Unique identifier of the node (can be NULL, in
+ * which case the next node without an id is matched).
+ * \param[in] value String value of the value to be compared.
+ * \param[out] bFound true if a matchin value was found.
+ * \returns String value for the reference value.
+ * \throws TestException if node creation fails in write mode.
+ *
+ * Performs common tasks in checking a reference value:
+ * finding/creating the correct XML node and reading/writing its string
+ * value. Caller is responsible for converting the value to and from
+ * string where necessary and performing the actual comparison.
+ *
+ * In read mode, if a value is not found, adds a Google Test failure
+ * and returns an empty string. If the reference value is found,
+ * returns it (\p value is not used in this case).
+ *
+ * In write mode, creates the node if it is not found, sets its value
+ * as \p value and returns \p value.
+ */
std::string processItem(const xmlChar *name, const char *id,
const char *value, bool *bFound);
+ //! Convenience wrapper that takes a std::string.
std::string processItem(const xmlChar *name, const char *id,
const std::string &value, bool *bFound);
+ /*! \brief
+ * Whether the checker should ignore all validation calls.
+ *
+ * This is used to ignore any calls within compounds for which
+ * reference data could not be found, such that only one error is
+ * issued for the missing compound, instead of every individual value.
+ */
bool shouldIgnore() const;
/*! \brief
* a compound node.
*
* Can be NULL, in which case this checker does nothing (doesn't even
- * report errors).
+ * report errors, see shouldIgnore()).
*/
xmlNodePtr _currNode;
/*! \brief
*/
int initReferenceData(int *argc, char **argv);
+/*! \libinternal \brief
+ * Internal testing namespace.
+ *
+ * This namespace is used to contain some implementation-specific functions and
+ * classes. These are not meant for direct access, but typically reside in
+ * visible headers because of implementation reasons.
+ */
namespace internal
{
TestReferenceChecker(const TestReferenceChecker &other);
~TestReferenceChecker();
+ //! Assigns a test reference checker.
TestReferenceChecker &operator =(const TestReferenceChecker &other);
//! Returns true if reference data is currently being written.
/*! \libinternal \brief
* Exception class for reporting errors in tests.
*
+ * This exception should be used for error conditions that are internal to the
+ * test, i.e., do not indicate errors in the tested code.
+ *
* \ingroup module_testutils
*/
class TestException : public GromacsException
{
public:
+ /*! \brief
+ * Creates a test exception object with the provided detailed reason.
+ *
+ * \param[in] reason Detailed reason for the exception.
+ */
explicit TestException(const std::string &reason)
: GromacsException(reason) {}
biod.pnpi.spb.ru / alexxy / gromacs.git / commitdiff