For issue #82.

Adds documentation comments for everything that doxygen now detects as not-documented.

Documentation/Doxyfile

@@ -435,7 +435,7 @@ LOOKUP_CACHE_SIZE      = 0
 # normally produced when WARNINGS is set to YES.
 # The default value is: NO.
 
-EXTRACT_ALL            = YES
+EXTRACT_ALL            = NO
 
 # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
 # be included in the documentation.

PlayRho/Collision/AABB.hpp

@@ -192,6 +192,7 @@ namespace playrho
         };
     };
 
+    /// @brief Gets an invalid AABB value.
     template <>
     constexpr AABB GetInvalid() noexcept
     {
@@ -204,6 +205,7 @@ namespace playrho
         return (aabb.GetLowerBound() + aabb.GetUpperBound()) / Real{2};
     }
 
+    /// @brief Gets dimensions of the given AABB.
     constexpr Length2D GetDimensions(const AABB aabb) noexcept
     {
         return aabb.GetUpperBound() - aabb.GetLowerBound();
@@ -224,35 +226,41 @@ namespace playrho
         return (GetX(dimensions) + GetY(dimensions)) * Real{2};
     }
 
+    /// @brief Gets the AABB that minimally encloses the given AABBs.
     constexpr AABB GetEnclosingAABB(AABB a, AABB b)
     {
         return a.Include(b);
     }
 
+    /// @brief Gets the AABB that the result of displacing the given AABB by the given
+    ///   displacement amount.
     constexpr AABB GetDisplacedAABB(AABB aabb, const Length2D displacement)
     {
         aabb.Displace(displacement);
         return aabb;
     }
-
+
+    /// @brief Gets the fattened AABB result.
     constexpr AABB GetFattenedAABB(AABB aabb, const Length amount)
     {
         aabb.Fatten(amount);
         return aabb;
     }
 
+    /// @brief Gets whether the two AABB objects are equal.
     constexpr bool operator== (const AABB lhs, const AABB rhs)
     {
         return (lhs.GetLowerBound() == rhs.GetLowerBound()) && (lhs.GetUpperBound() == rhs.GetUpperBound());
     }
 
+    /// @brief Gets whether the two AABB objects are not equal.
     constexpr bool operator!= (const AABB lhs, const AABB rhs)
     {
         return !(lhs == rhs);
     }
 
-    // Tests for overlap between two axis aligned bounding boxes.
-    // @note This function's complexity is constant.
+    /// @brief Tests for overlap between two axis aligned bounding boxes.
+    /// @note This function's complexity is constant.
     constexpr bool TestOverlap(const AABB a, const AABB b) noexcept
     {
         const auto d1 = b.GetLowerBound() - a.GetUpperBound();
@@ -271,8 +279,10 @@ namespace playrho
     /// @return AABB for the proxy shape or the default AABB if the proxy has a zero vertex count.
     AABB ComputeAABB(const DistanceProxy& proxy, const Transformation xf) noexcept;
 
+    /// @brief Computes the AABB for the given shape with the given transformation.
     AABB ComputeAABB(const Shape& shape, const Transformation xf);
 
+    /// @brief Computes the AABB for the given body.
     AABB ComputeAABB(const Body& body);
 
     /// Gets the fixture's AABB.

PlayRho/Collision/Collision.hpp

@@ -34,8 +34,9 @@
 namespace playrho
 {
 class Manifold;
-
-/// This is used for determining the state of contact points.
+
+/// @brief Point state enumeration.
+/// @note This is used for determining the state of contact points.
 enum class PointState
 {
     NullState, ///< point does not exist
@@ -49,22 +50,26 @@ enum class PointState
 ///   So state1 is either persist or remove while state2 is either add or persist.
 struct PointStates
 {
+    /// @brief State 1.
     PointState state1[MaxManifoldPoints] = {PointState::NullState, PointState::NullState};
+
+    /// @brief State 2.
     PointState state2[MaxManifoldPoints] = {PointState::NullState, PointState::NullState};
 };
 
 /// @brief Computes the point states given two manifolds.
 PointStates GetPointStates(const Manifold& manifold1, const Manifold& manifold2) noexcept;
 
-/// Used for computing contact manifolds.
+/// @brief Clip vertex.
+/// @details Used for computing contact manifolds.
 /// @note This data structure is 12-bytes large (on at least one 64-bit platform).
 struct ClipVertex
 {
     Length2D v; ///< Vertex of edge or polygon. 8-bytes.
     ContactFeature cf; ///< Contact feature information. 4-bytes.
 };
 
-/// Clip list for ClipSegmentToLine.
+/// @brief Clip list for ClipSegmentToLine.
 /// @sa ClipSegmentToLine.
 /// @note This data structure is at least 24-bytes large.
 using ClipList = ArrayList<ClipVertex, MaxManifoldPoints>;

PlayRho/Collision/ContactFeature.hpp

@@ -40,6 +40,7 @@ struct ContactFeature
 {
     using Index = std::uint8_t; ///< Index type.
 
+    /// @brief Type of the associated index value.
     enum Type : std::uint8_t
     {
         e_vertex = 0,
@@ -54,42 +55,48 @@ struct ContactFeature
     Index indexB; ///< Feature index on shape B
 };
 
+/// @brief Gets the vertex vertex contact feature for the given indices.
 constexpr ContactFeature GetVertexVertexContactFeature(ContactFeature::Index a,
                                                        ContactFeature::Index b) noexcept
 {
     return ContactFeature{ContactFeature::e_vertex, a, ContactFeature::e_vertex, b};
 }
 
+/// @brief Gets the vertex face contact feature for the given indices.
 constexpr ContactFeature GetVertexFaceContactFeature(ContactFeature::Index a,
                                                      ContactFeature::Index b) noexcept
 {
     return ContactFeature{ContactFeature::e_vertex, a, ContactFeature::e_face, b};
 }
 
+/// @brief Gets the face vertex contact feature for the given indices.
 constexpr ContactFeature GetFaceVertexContactFeature(ContactFeature::Index a,
                                                      ContactFeature::Index b) noexcept
 {
     return ContactFeature{ContactFeature::e_face, a, ContactFeature::e_vertex, b};
 }
 
+/// @brief Gets the face face contact feature for the given indices.
 constexpr ContactFeature GetFaceFaceContactFeature(ContactFeature::Index a,
                                                    ContactFeature::Index b) noexcept
 {
     return ContactFeature{ContactFeature::e_face, a, ContactFeature::e_face, b};
 }
 
-/// Flips contact features information.
+/// @brief Flips contact features information.
 constexpr ContactFeature Flip(ContactFeature val) noexcept
 {
     return ContactFeature{val.typeB, val.indexB, val.typeA, val.indexA};
 }
 
+/// @brief Determines if the given two contact features are equal.
 constexpr bool operator==(ContactFeature lhs, ContactFeature rhs) noexcept
 {
     return (lhs.typeA == rhs.typeA) && (lhs.indexA == rhs.indexA)
         && (lhs.typeB == rhs.typeB) && (lhs.indexB == rhs.indexB);
 }
 
+/// @brief Determines if the given two contact features are not equal.
 constexpr bool operator!=(ContactFeature lhs, ContactFeature rhs) noexcept
 {
     return !(lhs == rhs);

PlayRho/Collision/Distance.cpp

@@ -46,6 +46,7 @@ namespace {
                                           const DistanceProxy& proxyA, const Transformation& xfA,
                                           const DistanceProxy& proxyB, const Transformation& xfB)
     {
+        /// @brief Size type.
         using size_type = std::remove_const<decltype(MaxSimplexEdges)>::type;
 
         Simplex::Edges simplexEdges;

PlayRho/Collision/Distance.hpp

@@ -30,8 +30,8 @@ namespace playrho
     /// Witness Points.
     struct WitnessPoints
     {
-        Length2D a;
-        Length2D b;
+        Length2D a; ///< Point A.
+        Length2D b; ///< Point B.
     };
 
     /// Gets the witness points of the given simplex.
@@ -40,15 +40,18 @@ namespace playrho
     /// Distance Configuration.
     struct DistanceConf
     {
+        /// @brief Iteration type.
         using iteration_type = std::remove_const<decltype(DefaultMaxDistanceIters)>::type;
 
-        Simplex::Cache cache;
-        iteration_type maxIterations = DefaultMaxDistanceIters;
+        Simplex::Cache cache; ///< Cache.
+        iteration_type maxIterations = DefaultMaxDistanceIters; ///< Max iterations.
     };
 
     /// @brief Distance Output.
     struct DistanceOutput
     {
+
+        /// @brief State of the distance output.
         enum State: std::uint8_t
         {
             Unknown,
@@ -58,6 +61,7 @@ namespace playrho
             HitMaxIters
         };
 
+        /// @brief Iteration type.
         using iteration_type = std::remove_const<decltype(DefaultMaxDistanceIters)>::type;
 
         Simplex simplex; ///< Simplex.

PlayRho/Collision/DistanceProxy.hpp

@@ -45,10 +45,12 @@ namespace playrho
         /// @details Must be big enough to hold max posible count of vertices.
         using size_type = std::remove_const<decltype(MaxShapeVertices)>::type;
 
+        /// @brief Invalid index.
         static constexpr size_type InvalidIndex = static_cast<size_type>(-1);
 
         DistanceProxy() = default;
 
+        /// @brief Copy constructor.
         constexpr DistanceProxy(const DistanceProxy& copy) noexcept:
             m_vertices{copy.m_vertices},
             m_normals{copy.m_normals},
@@ -114,6 +116,7 @@ namespace playrho
             return m_vertices[index];
         }
 
+        /// @brief Gets the normal for the given index.
         auto GetNormal(size_type index) const noexcept
         {
             assert(index != InvalidIndex);
@@ -129,8 +132,10 @@ namespace playrho
         Length m_vertexRadius = Length{0}; ///< Radius of the vertices of the associated shape.
     };
 
+    /// @brief Determines with the two given distance proxies are equal.
     bool operator== (const DistanceProxy& lhs, const DistanceProxy& rhs) noexcept;
 
+    /// @brief Determines with the two given distance proxies are not equal.
     inline bool operator!= (const DistanceProxy& lhs, const DistanceProxy& rhs) noexcept
     {
         return !(lhs == rhs);
@@ -146,8 +151,10 @@ namespace playrho
     /// @sa GetVertexCount().
     DistanceProxy::size_type GetSupportIndex(const DistanceProxy& proxy, const Vec2 d) noexcept;
 
+    /// @brief Finds the lowest right most vertex in the given collection.
     std::size_t FindLowestRightMostVertex(Span<const Length2D> vertices);
 
+    /// @brief Gets the convex hull for the given collection of vertices as a vector.
     std::vector<Length2D> GetConvexHullAsVector(Span<const Length2D> vertices);
 
     /// Tests a point for containment in the given distance proxy.

PlayRho/Collision/DynamicTree.hpp

@@ -43,8 +43,13 @@ class DynamicTree
 {
 public:
 
+    /// @brief Size type.
     using size_type = std::remove_const<decltype(MaxContacts)>::type;
+
+    /// @brief Query callback type.
     using QueryCallback = std::function<bool(size_type)>;
+
+    /// @brief For each callback type.
     using ForEachCallback = std::function<void(size_type)>;
 
     /// @brief Ray cast callback function.
@@ -54,6 +59,7 @@ class DynamicTree
     /// @brief Invalid index value.
     static constexpr size_type InvalidIndex = static_cast<size_type>(-1);
 
+    /// @brief Gets the default initial node capacity.
     static constexpr size_type GetDefaultInitialNodeCapacity() noexcept;
 
     /// @brief Constructing the tree initializes the node pool.
@@ -62,9 +68,11 @@ class DynamicTree
     /// @brief Destroys the tree, freeing the node pool.
     ~DynamicTree() noexcept;
 
+    /// @brief Copy constructor.
     DynamicTree(const DynamicTree& copy);
 
-    DynamicTree& operator=(const DynamicTree& copy);
+    /// @brief Assignment operator.
+    DynamicTree& operator= (const DynamicTree& copy);
 
     /// @brief Creates a new proxy.
     /// @details Creates a proxy for a tight fitting AABB and a userData pointer.
@@ -88,6 +96,7 @@ class DynamicTree
     /// @return User data for the specified node.
     void* GetUserData(const size_type index) const noexcept;
 
+    /// @brief Sets the user data for the element at the given index to the given value.
     void SetUserData(const size_type index, void* value) noexcept;
 
     /// @brief Gets the AABB for a proxy.
@@ -99,6 +108,7 @@ class DynamicTree
     /// @note The callback instance is called for each proxy that overlaps the supplied AABB.
     void Query(const AABB aabb, QueryCallback callback) const;
 
+    /// @brief Calls the given callback for each of the entries overlapping the given AABB.
     void ForEach(const AABB aabb, ForEachCallback callback) const;
 
     /// @brief Ray-cast against the proxies in the tree.
@@ -131,6 +141,7 @@ class DynamicTree
     /// @return <code>true</code> if valid, <code>false</code> otherwise.
     bool ValidateMetrics(size_type index) const noexcept;
 
+    /// @brief Gets the root index.
     size_type GetRootIndex() const noexcept;
 
     /// @brief Gets the height of the binary tree.
@@ -170,6 +181,7 @@ class DynamicTree
     /// @brief Gets the current node capacity of this tree.
     size_type GetNodeCapacity() const noexcept;
 
+    /// @brief Sets the node capacity to the given value.
     void SetNodeCapacity(size_type value);
 
     /// @brief Gets the current node count.
@@ -292,6 +304,7 @@ inline DynamicTree::size_type DynamicTree::ComputeHeight() const noexcept
     return ComputeHeight(GetRootIndex());
 }
 
+/// @brief Tests for overlap of the elements identified in the given dynamic tree.
 inline bool TestOverlap(const DynamicTree& tree,
                         DynamicTree::size_type proxyIdA, DynamicTree::size_type proxyIdB)
 {

PlayRho/Collision/IndexPair.hpp

@@ -34,20 +34,24 @@ namespace playrho
         /// @details Must be big enough to hold max posible count of vertices.
         using size_type = std::remove_const<decltype(MaxShapeVertices)>::type;
 
+        /// @brief Invalid index.
         static constexpr size_type InvalidIndex = static_cast<size_type>(-1);
 
         size_type a; ///< Index of vertex from shape A.
         size_type b; ///< Index of vertex from shape B.
     };
 
+    /// @brief Invalid index pair value.
     constexpr auto InvalidIndexPair = IndexPair{IndexPair::InvalidIndex, IndexPair::InvalidIndex};
 
-    constexpr inline bool operator == (IndexPair lhs, IndexPair rhs)
+    /// @brief Determines whether the two given index pairs are equal.
+    constexpr inline bool operator== (IndexPair lhs, IndexPair rhs)
     {
         return (lhs.a == rhs.a) && (lhs.b == rhs.b);
     }
 
-    constexpr inline bool operator != (IndexPair lhs, IndexPair rhs)
+    /// @brief Determines whether the two given index pairs are not equal.
+    constexpr inline bool operator!= (IndexPair lhs, IndexPair rhs)
     {
         return (lhs.a != rhs.a) || (lhs.b != rhs.b);
     }
@@ -58,6 +62,7 @@ namespace playrho
 
     static_assert(MaxSimplexEdges == 3, "Invalid assumption about size of MaxSimplexEdges");
 
+    /// @brief Gets the number of valid indices in the given collection of index pairs.
     constexpr inline std::size_t GetNumIndices(IndexPair3 pairs) noexcept
     {
         return std::size_t{3}