Fix various issues in Doxygen documentation

OpenSim/Actuators/PolynomialPathFitter.h

@@ -73,8 +73,7 @@ class OSIMACTUATORS_API PolynomialPathFitterBounds : public Object {
  *       directory to which the results are written can be specified using the
  *      `setOutputDirectory` method.
  *
- * Settings
- * --------
+ * # Settings
  * Various settings can be adjusted to control the path fitting process. The
  * `setMomentArmsThreshold` method determines whether or not a path depends on a
  * model coordinate. In other words, the absolute value the moment arm of a with
@@ -91,10 +90,10 @@ class OSIMACTUATORS_API PolynomialPathFitterBounds : public Object {
  * lengths computed from the original model paths and the fitted polynomial
  * paths. The `setNumSamplesPerFrame` method specifies the number of samples
  * taken per time frame in the coordinate values table used to fit each path.
- * The `setParallel` method specifies the number of threads used to parallelize
- * the path fitting process. The `setLatinHypercubeAlgorithm` method specifies
- * the Latin hypercube sampling algorithm used to sample coordinate values for
- * path fitting.
+ * The `setNumParallelThreads` method specifies the number of threads used to 
+ * parallelize the path fitting process. The `setLatinHypercubeAlgorithm` method 
+ * specifies the Latin hypercube sampling algorithm used to sample coordinate 
+ * values for path fitting.
  *
  * The default settings are as follows:
  *
@@ -113,8 +112,7 @@ class OSIMACTUATORS_API PolynomialPathFitterBounds : public Object {
  *       models with larger or smaller anatomical measures (e.g., dinosaur
  *       models).
  *
- * Usage
- * -----
+ * # Usage
  * The most basic usage of `PolynomialPathFitter` requires the user to provide
  * a model and reference trajectory. The model should contain at least one path
  * object derived from `AbstractGeometryPath` and should not contain any
@@ -145,8 +143,7 @@ class OSIMACTUATORS_API PolynomialPathFitterBounds : public Object {
  * fitter.run();
  * @endcode
  *
- * Recommendations
- * ---------------
+ * # Recommendations
  * Information from each step of the path fitting process is logged to the
  * console, provided that you have set the OpenSim::Logger to level "info" or
  * greater. Warnings are printed if the number of samples is likely insufficient
@@ -408,7 +405,7 @@ class OSIMACTUATORS_API PolynomialPathFitter : public Object {
      *       of available hardware threads.
      */
     void setNumParallelThreads(int numThreads);
-    /// @copydoc setParallel()
+    /// @copydoc setNumParallelThreads(int numThreads)
     int getNumParallelThreads() const;
 
     /**

OpenSim/Common/LatinHypercubeDesign.h

@@ -30,28 +30,33 @@ namespace OpenSim {
 
 /**
  * A class for generating Latin hypercube designs.
+ * 
+ * # Latin hypercube design
  *
  * A Latin hypercube is an m-by-n matrix, where 'm' is the number of design
  * samples and 'n' is the number of variables in the design. Each sample point
  * (i.e., each row in the design) is the only sample point in its row and column
  * in the hypercube defined by the number of variables. 
- *
+ * 
+ * \cond 
  * For example, consider a design with 5 samples and 2 variables:
  *
- *            grid                       matrix
- *       __ __ __ __ __                __       __
- *      |    x         |              | 0.6  0.2 |
- *      |         x    |              | 1.0  0.4 |
- *   q2 | x            |          q = | 0.2  0.6 |
- *      |            x |              | 0.8  0.8 |
- *      |      x       |              | 0.4  1.0 |
- *       ‾‾ ‾‾ ‾‾ ‾‾ ‾‾               ‾‾       ‾‾
+ *             grid                         matrix
+ *        __ __ __ __ __                  __      __
+ *       |    x         |                | 0.6  0.2 |
+ *       |         x    |                | 1.0  0.4 |
+ *   q2  | x            |          q  =  | 0.2  0.6 |
+ *       |            x |                | 0.8  0.8 |
+ *       |      x       |                | 0.4  1.0 |
+ *        ‾‾ ‾‾ ‾‾ ‾‾ ‾‾                  ‾‾      ‾‾
  *             q1
- *
+ *  
  * On the left is the 5-by-5 square grid (i.e., 2-D hypercube) that is produced
  * if the samples are plotted in the variable space defined by q1 and q2. On the
  * right is the 5-by-2 design matrix that contains the 5 samples.
- *             
+ * \endcond
+ * 
+ *
  * Latin hypercube designs are useful for sampling large, multivariate parameter 
  * spaces. Optimal Latin hypercube designs are those that maximize the minimum 
  * distance between samples in the design. This class provides methods for 
@@ -60,8 +65,7 @@ namespace OpenSim {
  * algorithm from Viana et al. (2009) and the enhanced stochastic evolutionary
  * algorithm from Jin et al. (2005).
  *
- * How to create a Latin hypercube design
- * --------------------------------------
+ * # How to create a Latin hypercube design
  * To create a Latin hypercube design, you must first specify the number of
  * variables and samples in the design, and, optionally, the distance criterion
  * used to evaluate each design. The distance criterion can be either "maximin"
@@ -103,8 +107,7 @@ namespace OpenSim {
  * minimization criterion. While both criteria aim to achieve a similar goal,
  * the values returned by each are not directly comparable.
  *
- * Recommendations for different sized designs
- * -------------------------------------------
+ * # Recommendations for different sized designs
  * To rapidly create a random Latin hypercube design of any size,
  * generateRandomDesign() is recommended. This method is fast, but does not
  * guarantee that the design is optimal.
@@ -124,8 +127,7 @@ namespace OpenSim {
  * it is recommended to use the "phi_p" distance criterion, which approximates
  * "maximin", but is much faster.
  *
- * References
- * ----------
+ * # References
  * - [1] Viana, F.A.C., Venter, G. and Balabanov, V. (2010), An algorithm for
  *       fast optimal Latin hypercube design of experiments. Int. J. Numer. Meth.
  *       Engng., 82: 135-156. https://doi.org/10.1002/nme.2750

OpenSim/Common/Object.h

@@ -341,7 +341,9 @@ class OSIMCOMMON_API Object
     used by the Property declaration macros for fast access to properties. **/
     template <class T> const Property<T>& 
     getProperty(const PropertyIndex& index) const;
-    /** @copydoc getProperty(const PropertyIndex&) **/
+    /** Get property of known type Property\<T> as a const reference; 
+    the property must be present and have the right type. This is primarily
+    used by the Property declaration macros for fast access to properties. **/
     template <class T> const Property<T>&
     getPropertyByName(const std::string& name) const;
 

OpenSim/Moco/MocoGoal/MocoOrientationTrackingGoal.h

@@ -86,7 +86,7 @@ class OSIMMOCO_API MocoOrientationTrackingGoal : public MocoGoal {
         set_rotation_reference_file("");
         m_rotation_table = ref;
     }
-    /** @copydoc setRotationReference(const TimeSeriesTable_<SimTK::Rotation>& ref) */
+    /** @copydoc setRotationReference(const TimeSeriesTable_<SimTK::Rotation_<double>>& ref) */
     void setRotationReference(const TimeSeriesTable_<SimTK::Quaternion_<double>>& ref) {
         set_states_reference(TableProcessor());
         set_rotation_reference_file("");

OpenSim/Moco/MocoGoal/MocoOutputGoal.h

@@ -190,7 +190,7 @@ The goal is computed as follows:
 
 \f[
 \frac{1}{dm} \int_{t_i}^{t_f} 
-    w_v\beta((\frac{1}{s} (\ln (1 + \exp (s\betav))))^p) ~dt
+    w_v \beta((\frac{1}{s} (\ln (1 + \exp (s \beta v))))^p) ~dt
 \f]
 We use the following notation:
 - \f$ d \f$: displacement of the system, if `divide_by_displacement` is
@@ -199,8 +199,8 @@ We use the following notation:
   true; 1 otherwise.
 - \f$ v \f$: the output variable of choice.
 - \f$ w_v \f$: the weight for output variable \f$ v \f$.
-- \f$ \beta \f$: the approximate extremum to be taken (\beta == -1 for
-  minimum; \beta == 1 for maximum).
+- \f$ \beta \f$: the approximate extremum to be taken (\f$ \beta \f$ == -1 for
+  minimum; \f$ \beta \f$ == 1 for maximum).
 - \f$ s \f$: the smoothing factor for approximating the extremum. With
   \f$ s \f$ == 1 the approximation is closer to the true extremum taken.
   For \f$ v \f$ with potentially large magnitudes (> 2000) during a simulation

OpenSim/Moco/MocoUtilities.h

@@ -245,20 +245,20 @@ class FileDeletionThrower {
 /// In general, this utility needs getRecordValues() to report the
 /// following force and torque information at the specified indices:
 ///
-/// index - component (body)
-/// ------------------------
-///     0 - force-x (foot)
-///     1 - force-y (foot)
-///     2 - force-z (foot)
-///     3 - torque-x (foot)
-///     4 - torque-y (foot)
-///     5 - torque-z (foot)
-///     6 - force-x (contact plane)
-///     7 - force-y (contact plane)
-///     8 - force-z (contact plane)
-///     9 - torque-x (contact plane)
-///    10 - torque-y (contact plane)
-///    11 - torque-z (contact plane)
+/// index | component (body)
+/// ----- | ----------------
+///     0 | force-x (foot)
+///     1 | force-y (foot)
+///     2 | force-z (foot)
+///     3 | torque-x (foot)
+///     4 | torque-y (foot)
+///     5 | torque-z (foot)
+///     6 | force-x (contact plane)
+///     7 | force-y (contact plane)
+///     8 | force-z (contact plane)
+///     9 | torque-x (contact plane)
+///    10 | torque-y (contact plane)
+///    11 | torque-z (contact plane)
 ///
 /// @ingroup mocoutil
 OSIMMOCO_API

OpenSim/Simulation/Model/FunctionBasedPath.h

@@ -94,8 +94,7 @@ namespace OpenSim {
  * the tension in the path by the moment arms. Therefore, this class only
  * applies mobility (i.e., generalized) forces to the model.
  *
- * References
- * ----------
+ * # References
  * - [1] Meyer AJ, Patten C, Fregly BJ (2017) "Lower extremity EMG-driven
  *       modeling of walking with automated adjustment of musculoskeletal
  *       geometry." PLoS ONE 12(7): e0179698.

OpenSim/Simulation/TableProcessor.h

@@ -228,7 +228,7 @@ class OSIMSIMULATION_API TabOpUseAbsoluteStateNames : public TableOperator {
     }
 };
 
-/// Invoke SimulationUtilities::appendCoupledCoordinateValues() on the table.
+/** Invoke SimulationUtilities::appendCoupledCoordinateValues() on the table. */
 class OSIMSIMULATION_API TabOpAppendCoupledCoordinateValues
         : public TableOperator {
     OpenSim_DECLARE_CONCRETE_OBJECT(TabOpAppendCoupledCoordinateValues,
@@ -256,8 +256,8 @@ class OSIMSIMULATION_API TabOpAppendCoupledCoordinateValues
     }
 };
 
-/// Invoke SimulationUtilities::appendCoordinateValueDerivativesAsSpeeds() on
-/// the table.
+/** Invoke SimulationUtilities::appendCoordinateValueDerivativesAsSpeeds() on
+the table */
 class OSIMSIMULATION_API TabOpAppendCoordinateValueDerivativesAsSpeeds
         : public TableOperator {
     OpenSim_DECLARE_CONCRETE_OBJECT(

doc/Moco/MocoExamples.dox

@@ -47,8 +47,6 @@ EMG-driven simulation of walking.
 @example exampleMinimizeJointReaction.m
 This is an example of MocoJointReactionGoal.
 
-
-
 @example exampleOptimizeMass.m
 A simple parameter optimization example.
 
@@ -63,6 +61,9 @@ This is Moco's simplest example.
 This example conducts a 2-D prediction of walking, employing a
 MocoPerodicityGoal.
 
+@example examplePolynomialPathFitter.m
+This example demonstrates how to use PolynomialPathFitter to 
+create a set of FunctionBasedPaths for a model.
 
 
 @example exampleMocoTrack.py
@@ -124,6 +125,10 @@ MocoSolution.
 This example demonstrates how Moco solves problems with kinematic constraints
 and includes a visualization of the Lagrange multipliers that Moco solves for.
 
+@example examplePolynomialPathFitter.py
+This example demonstrates how to use PolynomialPathFitter to 
+create a set of FunctionBasedPaths for a model.
+
 
 
 @example example2DWalking.cpp
@@ -211,6 +216,7 @@ IMUTracking | torque-driven single leg | MocoStudy motion prediction, MocoAccele
 EMGTracking | lower-limb | MocoInverse, MocoControlTrackingGoal | [MATLAB](@ref exampleEMGTracking_answers.m) [Python](@ref exampleEMGTracking_answers.py)
 PredictAndTrack | double pendulum | MocoMarkerFinalGoal, MocoFinalTimeGoal, MocoMarkerTrackingGoal, MocoStateTrackingGoal | [Python](@ref examplePredictAndTrack.py)
 PrototypeCustomGoal | N/A | Sandbox for defining a custom MocoGoal | [MATLAB](@ref examplePrototypeCustomGoal.m)
+PolynomialPathFitter | N/A | Fit FunctionBasedPath%s to a model | [MATLAB](@ref examplePolynomialPathFitter.m) [Python](@ref examplePolynomialPathFitter.py)
 
 @section Advanced
 

doc/doxyfile_shared.in

@@ -965,7 +965,9 @@ EXCLUDE_SYMBOLS        =
 
 EXAMPLE_PATH           = "@PROJECT_SOURCE_DIR@/OpenSim/Tests/README/testREADME.cpp" \
                          "@PROJECT_SOURCE_DIR@/Bindings/Java/Matlab/examples/Moco" \
+                         "@PROJECT_SOURCE_DIR@/Bindings/Java/Matlab/examples/PolynomialPathFitter" \
                          "@PROJECT_SOURCE_DIR@/Bindings/Python/examples/Moco" \
+                         "@PROJECT_SOURCE_DIR@/Bindings/Python/examples/PolynomialPathFitter" \
                          "@PROJECT_SOURCE_DIR@/OpenSim/Examples/Moco"
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the