Changes for issue #217...

- Adds documentation comments regarding use of visitor pattern.
- Updates documentation comments to more thoroughly explain what types can be used for the Real type alias.

Author: louis-langholtz

PlayRho/Collision/Shapes/Shape.hpp

@@ -43,13 +43,15 @@ struct ShapeDef;
 ///
 /// @details This is a polymorphic abstract base class for shapes.
 ///   A shape is used for collision detection. You can create a shape however you like.
-///   Shapes used for simulation in World are created automatically when a Fixture
-///   is created. Shapes may encapsulate zero or more child shapes.
+///   Shapes used for simulation in <code>World</code> are created automatically when a
+///   <code>Fixture</code> is created. Shapes may encapsulate zero or more child shapes.
 ///
 /// @note This data structure is 32-bytes large (on at least one 64-bit platform).
 ///
 /// @ingroup PartsGroup
 ///
+/// @sa Fixture
+///
 class Shape
 {
 public:
@@ -73,6 +75,10 @@ class Shape
     virtual MassData GetMassData() const noexcept = 0;
 
     /// @brief Accepts a visitor.
+    /// @details This is the Accept method definition of a "visitor design pattern" for
+    ///   for doing shape subclass specific types of processing for a constant shape.
+    /// @sa ShapeVisitor
+    /// @sa https://en.wikipedia.org/wiki/Visitor_pattern
     virtual void Accept(ShapeVisitor& visitor) const = 0;
 
     /// @brief Gets the vertex radius.

PlayRho/Common/Fixed.hpp

@@ -33,14 +33,17 @@
 
 namespace playrho
 {
-    /// @brief A fixed-point template class.
+    /// @brief Template class for fixed-point numbers.
     ///
     /// @details This is a fixed point type template for a given base type using a given number
-    ///   of fraction bits.
+    ///   of fraction bits that satisfies the "LiteralType" concept.
     ///
     /// @note For a 32-bit sized fixed point type with a 14-bit fraction part
     ///   0.000061035156250 is the smallest double precision value that can be represented.
     ///
+    /// @sa https://en.wikipedia.org/wiki/Fixed-point_arithmetic
+    /// @sa http://en.cppreference.com/w/cpp/concept/LiteralType
+    ///
     template <typename BASE_TYPE, unsigned int FRACTION_BITS>
     class Fixed
     {

PlayRho/Common/Real.hpp

@@ -38,23 +38,31 @@ namespace playrho {
 ///   real-numbers. Ideally the implementation of this type doesn't suffer from things like:
 ///   catastrophic cancellation, catastrophic division, overflows, nor underflows.
 ///
-/// @note This can be implemented using float, double, long double, Fixed64, or Fixed32
-///   (though the use of Fixed32 is discouraged).
+/// @note This can be implemented using any of the fundamental floating point types (
+///   <code>float</code>, <code>double</code>, or <code>long double</code>).
+/// @note This can also be implemented using a "LiteralType" that has the necessary support:
+///   all common mathematical functions, support for infinity and NaN, and a specialization
+///   of the <code>std::numeric_limits</code> class template for it.
+/// @note At present, the <code>Fixed32</code> and <code>Fixed64</code> aliases of the
+///   <code>Fixed</code> template type are provided as examples of qualifying literal types
+///   though the usability of <code>Fixed32</code> is limited and its use is discouraged.
 ///
 /// @note Regarding division:
+///  - While dividing 1 by a real, caching the result, and then doing multiplications with the
+///    result may well be faster (than repeatedly dividing), dividing 1 by the real can also
+///    result in an underflow situation that's then compounded every time it's multiplied with
+///    other values.
+///  - Meanwhile, dividing every time by a real isolates any underflows to the particular
+///    division where underflow occurs.
 ///
-///   While dividing 1 by a Real, caching the result, and then doing multiplications with the
-///   result may well be faster (than repeatedly dividing), dividing 1 by Real can also result
-///   in an underflow situation that's then compounded every time it's multiplied with other
-///   values.
-///
-///   Meanwhile, dividing every value by Real isolates any underflows to the particular
-///   division where underflow occurs.
-///
-/// @warning Using Fixed32 is not advised as it's numerical limitations are more likely to
-///   result in problems like overflows or underflows.
+/// @warning Using <code>Fixed32</code> is not advised as it's numerical limitations are more
+///   likely to result in problems like overflows or underflows.
 /// @warning The note regarding division applies even more so when using a fixed-point type
-///   (for Real).
+///   (for <code>Real</code>).
+///
+/// @sa http://en.cppreference.com/w/cpp/language/types
+/// @sa http://en.cppreference.com/w/cpp/types/is_floating_point
+/// @sa http://en.cppreference.com/w/cpp/concept/LiteralType
 ///
 using Real = float;
 

PlayRho/Common/Real.hpp.in

@@ -38,23 +38,31 @@ namespace playrho {
 ///   real-numbers. Ideally the implementation of this type doesn't suffer from things like:
 ///   catastrophic cancellation, catastrophic division, overflows, nor underflows.
 ///
-/// @note This can be implemented using float, double, long double, Fixed64, or Fixed32
-///   (though the use of Fixed32 is discouraged).
+/// @note This can be implemented using any of the fundamental floating point types (
+///   <code>float</code>, <code>double</code>, or <code>long double</code>).
+/// @note This can also be implemented using a "LiteralType" that has the necessary support:
+///   all common mathematical functions, support for infinity and NaN, and a specialization
+///   of the <code>std::numeric_limits</code> class template for it.
+/// @note At present, the <code>Fixed32</code> and <code>Fixed64</code> aliases of the
+///   <code>Fixed</code> template type are provided as examples of qualifying literal types
+///   though the usability of <code>Fixed32</code> is limited and its use is discouraged.
 ///
 /// @note Regarding division:
+///  - While dividing 1 by a real, caching the result, and then doing multiplications with the
+///    result may well be faster (than repeatedly dividing), dividing 1 by the real can also
+///    result in an underflow situation that's then compounded every time it's multiplied with
+///    other values.
+///  - Meanwhile, dividing every time by a real isolates any underflows to the particular
+///    division where underflow occurs.
 ///
-///   While dividing 1 by a Real, caching the result, and then doing multiplications with the
-///   result may well be faster (than repeatedly dividing), dividing 1 by Real can also result
-///   in an underflow situation that's then compounded every time it's multiplied with other
-///   values.
-///
-///   Meanwhile, dividing every value by Real isolates any underflows to the particular
-///   division where underflow occurs.
-///
-/// @warning Using Fixed32 is not advised as it's numerical limitations are more likely to
-///   result in problems like overflows or underflows.
+/// @warning Using <code>Fixed32</code> is not advised as it's numerical limitations are more
+///   likely to result in problems like overflows or underflows.
 /// @warning The note regarding division applies even more so when using a fixed-point type
-///   (for Real).
+///   (for <code>Real</code>).
+///
+/// @sa http://en.cppreference.com/w/cpp/language/types
+/// @sa http://en.cppreference.com/w/cpp/types/is_floating_point
+/// @sa http://en.cppreference.com/w/cpp/concept/LiteralType
 ///
 using Real = @PLAYRHO_REAL_TYPE@;
 

PlayRho/Common/RealConstants.hpp

@@ -29,6 +29,7 @@
 #ifndef PLAYRHO_COMMON_REALCONSTANTS_HPP
 #define PLAYRHO_COMMON_REALCONSTANTS_HPP
 
+#include <PlayRho/Defines.hpp>
 #include <PlayRho/Common/Real.hpp>
 
 namespace playrho {

PlayRho/Dynamics/Joints/Joint.hpp

@@ -105,9 +105,17 @@ class Joint
     virtual AngularMomentum GetAngularReaction() const = 0;
 
     /// @brief Accepts a visitor.
+    /// @details This is the Accept method definition of a "visitor design pattern" for
+    ///   for doing joint subclass specific types of processing for a constant joint.
+    /// @sa JointVisitor
+    /// @sa https://en.wikipedia.org/wiki/Visitor_pattern
     virtual void Accept(JointVisitor& visitor) const = 0;
 
     /// @brief Accepts a visitor.
+    /// @details This is the Accept method definition of a "visitor design pattern" for
+    ///   for doing joint subclass specific types of processing.
+    /// @sa JointVisitor
+    /// @sa https://en.wikipedia.org/wiki/Visitor_pattern
     virtual void Accept(JointVisitor& visitor) = 0;
 
     /// Get the user data pointer.