[sampling][disk] improve docu

frackit/sampling/disksampler.hh

@@ -18,7 +18,12 @@
  *****************************************************************************/
 /*!
  * \file
- * \brief \todo TODO Doc me.
+ * \brief Class to randomly generate disks in three-
+ *        dimensional space. Generation is done on the
+ *        basis of probability distribution functions
+ *        provided among construction. The type of
+ *        distribution function used in the sampler
+ *        class can be defined by passing a traits class.
  */
 #ifndef FRACKIT_DISK_SAMPLER_HH
 #define FRACKIT_DISK_SAMPLER_HH
@@ -40,16 +45,41 @@ namespace Frackit {
 template<class ctype>
 struct DefaultSamplerTraits<Disk<ctype>>
 {
+    // Distribution used for the major axis length
     using MajorAxisLengthDistribution = std::normal_distribution<ctype>;
+    // Distribution used for the minor axis length
     using MinorAxisLengthDistribution = std::normal_distribution<ctype>;
 
+    // The following distribution determine the rotation angles
+    // around the x-, y- and z- axis that have to be performed
+    // subsequently (!) to rotate the standard basis of R^3 into the
+    // disk local basis. The disk local basis is defined such that
+    // the major axis is the first basis vector, the minor axis
+    // the second basis vector and the normal vector the third.
+    // We chose this approach as these three parameters can be
+    // sampled independently, while the major/minor/normal axes
+    // cannot be chosen independently.
     using XAngleDistribution = std::normal_distribution<ctype>;
     using YAngleDistribution = std::normal_distribution<ctype>;
     using ZAngleDistribution = std::normal_distribution<ctype>;
 };
 
 /*!
- * \brief Geometry sampler for disks
+ * \brief Geometry sampler for disks.
+ *        The disks are generated by sampling from provided
+ *        distributions for:
+ *            - major axis length
+ *            - minor axis length
+ *            - rotation angle of standard basis around x-axis
+ *            - rotation angle of standard basis around y-axis
+ *            - rotation angle of standard basis around z-axis
+ *        The rotation angles are used to define the local basis
+ *        of the disk, composed of major axis, minor axis and normal.
+ *        The angles state around which angles the standard basis of R^3
+ *        has to be rotated around the x-, y- and the z-axis (subsequently!)
+ *        for it to describe the disk-local basis. This approach was chosen
+ *        since independent sampling of the axis vectors is not possible
+ *        due to the requirement that they must form an orthonormal basis.
  */
 template< class ctype, class T >
 class GeometrySampler< Disk<ctype>, T >
@@ -72,7 +102,14 @@ public:
     using Traits = T;
 
     /*!
-     * \brief \todo TODO Doc me.
+     * \brief Constructor.
+     * \param majAxis Distribution used to sample major axis lengths
+     * \param minAxis Distribution used to sample minor axis lengths
+     * \param xAngle Distribution used to sample the angle of rotation around x-axis
+     * \param yAngle Distribution used to sample the angle of rotation around y-axis
+     * \param zAngle Distribution used to sample the angle of rotation around z-axis
+     * \note For more info on the meaning of the rotation angles, see the description
+     *       of this class.
      */
     GeometrySampler(const MajorAxisLengthDistribution& majAxis,
                     const MinorAxisLengthDistribution& minAxis,