Added documentation, added @brief

Additionally: Using '//' for the forward declarations so they don't get picked up by doxygen

include/eos/core/Landmark.hpp

@@ -30,23 +30,23 @@ namespace eos {
 	namespace core {
 
 /**
- * Representation of a landmark, consisting of a landmark name and
- * coordinates of the given type. Usually, the type would be cv::Vec2f.
+ * @brief Representation of a landmark, consisting of a landmark name and
+ * coordinates of the given type. Usually, the type would be \c cv::Vec2f.
  */
 template<class LandmarkType>
 struct Landmark
 {
-	std::string name;
-	LandmarkType coordinates;
+	std::string name; ///< Name of the landmark, often used as identifier.
+	LandmarkType coordinates; ///< The position or coordinates of the landmark.
 };
 
 /**
- * A trivial collection of landmarks that somehow belong together.
+ * @brief A trivial collection of landmarks that belong together.
  */
 template<class LandmarkType> using LandmarkCollection = std::vector<Landmark<LandmarkType>>;
 
 /**
- * Filters the given LandmarkCollection and returns a new LandmarkCollection
+ * @brief Filters the given LandmarkCollection and returns a new LandmarkCollection
  * containing all landmarks whose name matches the one given by \p filter.
  *
  * @param[in] landmarks The input LandmarkCollection to be filtered.

include/eos/core/LandmarkMapper.hpp

@@ -38,27 +38,39 @@ namespace eos {
 	namespace core {
 
 /**
- * Represents a mapping from one kind of landmarks
- * to a different format. Mappings are stored in a
- * file (see share/ for an example for ibug landmarks).
+ * @brief Represents a mapping from one kind of landmarks
+ * to a different format (e.g. model vertices).
+ *
+ * When fitting the 3D model to an image, a correspondence must
+ * be known from the 2D image landmarks to 3D vertex points in
+ * the Morphable Model. The 3D model defines all its points in
+ * the form of vertex ids.
+ * These mappings are stored in a file, see the \c share/ folder for
+ * an example for mapping 2D ibug landmarks to 3D model vertex indices.
+ *
+ * The LandmarkMapper thus has two main use cases:
+ * - Mapping 2D landmark points to 3D vertices
+ * - Converting one set of 2D landmarks into another set of 2D
+ *   landmarks with different identifiers.
  */
 class LandmarkMapper {
 public:
 	/**
-	 * Constructs a new landmark mapper that performs an identity mapping,
-	 * that is, its output is the same as the input.
-	 *
+	 * @brief Constructs a new landmark mapper that performs an identity
+	 * mapping, that is, its output is the same as the input.
 	 */
 	LandmarkMapper() = default;
 
 	/**
-	 * Constructs a new landmark mapper from a mappings-file.
+	 * @brief Constructs a new landmark mapper from a file containing
+	 * mappings from one set of landmark identifiers to another.
+	 *
 	 * In case the file contains no mappings, a landmark mapper
 	 * that performs an identity mapping is constructed.
 	 *
 	 * @param[in] filename A file with landmark mappings.
-	 * @throws runtime_error exception if there is an error
-	 *         loading the mappings from the file.
+	 * @throws runtime_error if there is an error loading
+	 *         the mappings from the file.
 	 */
 	LandmarkMapper(boost::filesystem::path filename)
 	{
@@ -87,7 +99,7 @@ public:
 	};
 
 	/**
-	 * Converts the given landmark name to the mapped name.
+	 * @brief Converts the given landmark name to the mapped name.
 	 *
 	 * @param[in] landmark_name A landmark name to convert.
 	 * @return The mapped landmark name if a mapping exists, an empty optional otherwise.
@@ -113,7 +125,7 @@ public:
 	};
 
 	/**
-	 * Returns the number of loaded landmark mappings.
+	 * @brief Returns the number of loaded landmark mappings.
 	 *
 	 * @return The number of landmark mappings.
 	 */

include/eos/morphablemodel/MorphableModel.hpp

@@ -34,9 +34,7 @@
 #include <vector>
 #include <array>
 
-/**
- * Forward declaration of an internal function
- */
+// Forward declaration of an internal function
 namespace eos { namespace morphablemodel { namespace detail {
 	eos::render::Mesh sample_to_mesh(cv::Mat shape, cv::Mat color, std::vector<std::array<int, 3>> tvi, std::vector<std::array<int, 3>> tci, std::vector<cv::Vec2f> texture_coordinates = std::vector<cv::Vec2f>());
 } } }

include/eos/morphablemodel/PcaModel.hpp

@@ -37,14 +37,12 @@
 namespace eos {
 	namespace morphablemodel {
 
-/**
- * Forward declarations of free functions
- */
+// Forward declarations of free functions
 cv::Mat normalise_pca_basis(cv::Mat unnormalisedBasis, cv::Mat eigenvalues);
 cv::Mat unnormalise_pca_basis(cv::Mat normalisedBasis, cv::Mat eigenvalues);
 
 /**
- * This class represents a PCA-model that consists of:
+ * @brief This class represents a PCA-model that consists of:
  *   - a mean vector (y x z)
  *   - a PCA basis matrix (unnormalised and normalised)
  *   - a PCA variance vector.
@@ -183,7 +181,7 @@ public:
 	 * Each column of the matrix is an eigenvector.
 	 * The returned basis is normalised, i.e. every eigenvector
 	 * is normalised by multiplying it with the square root of its eigenvalue.
-	 * 
+	 *
 	 * Returns a clone of the matrix so that the original cannot
 	 * be modified. TODO: No, don't return a clone.
 	 *
@@ -193,7 +191,7 @@ public:
 	{
 		return normalised_pca_basis.clone();
 	};
-	
+
 	/**
 	 * Returns the PCA basis for a particular vertex.
 	 * The returned basis is normalised, i.e. every eigenvector
@@ -249,7 +247,7 @@ public:
 
 private:
 	std::mt19937 engine; ///< Random number engine used to draw random coefficients.
-	
+
 	cv::Mat mean; ///< A 3m x 1 col-vector (xyzxyz...)', where m is the number of model-vertices.
 	cv::Mat normalised_pca_basis; ///< The normalised PCA basis matrix. m x n (rows x cols) = numShapeDims x numShapePcaCoeffs, (=eigenvector matrix V). Each column is an eigenvector.
 	cv::Mat unnormalised_pca_basis; ///< The unnormalised PCA basis matrix. m x n (rows x cols) = numShapeDims x numShapePcaCoeffs, (=eigenvector matrix V). Each column is an eigenvector.

include/eos/morphablemodel/io/cvssp.hpp

@@ -38,9 +38,7 @@
 namespace eos {
 	namespace morphablemodel {
 
-/**
- * Forward declarations
- */
+// Forward declaration
 std::vector<cv::Vec2f> load_isomap(boost::filesystem::path isomap_file);
 
 /**

include/eos/morphablemodel/io/mat_cerealisation.hpp

@@ -27,14 +27,13 @@
 #include "opencv2/core/core.hpp"
 
 /**
- * Serialisation for OpenCV cv::Mat matrices for the serialisation
+ * @brief Serialisation of OpenCV \c cv::Mat matrices for the serialisation
  * library cereal (http://uscilab.github.io/cereal/index.html).
  */
-
 namespace cv {
 
 /**
- * Serialise a cv::Mat using cereal.
+ * @brief Serialise a cv::Mat using cereal.
  *
  * Supports all types of matrices as well as non-contiguous ones.
  *
@@ -69,7 +68,7 @@ void save(Archive& ar, const cv::Mat& mat)
 };
 
 /**
- * De-serialise a cv::Mat using cereal.
+ * @brief De-serialise a cv::Mat using cereal.
  *
  * Supports all types of matrices as well as non-contiguous ones.
  *
@@ -101,7 +100,7 @@ void load(Archive& ar, cv::Mat& mat)
 };
 
 /**
- * Serialisation for a cv::Vec2f using cereal.
+ * @brief Serialisation of a cv::Vec2f using cereal.
  *
  * @param[in] ar The archive to (de)serialise.
  * @param[in] vec The vector to (de)serialise.