Improved docs

gtsam/hybrid/GaussianMixture.h

@@ -188,8 +188,9 @@ class GTSAM_EXPORT GaussianMixture
    *
    *    error(x;y,m) = K - log(probability(x;y,m))
    *
-   * For all x,y,m. But note that K, for the GaussianMixture, cannot depend on
-   * any arguments. Hence, we delegate to the underlying Gaussian
+   * For all x,y,m. But note that K, the (log) normalization constant defined
+   * in Conditional.h, should not depend on x, y, or m, only on the parameters
+   * of the density. Hence, we delegate to the underlying Gaussian
    * conditionals, indexed by m, which do satisfy:
    * 
    *    log(probability_m(x;y)) = K_m - error_m(x;y)

gtsam/inference/Conditional.h

@@ -38,7 +38,9 @@ namespace gtsam {
    *   probability(x) = k exp(-error(x))
    * where k is a normalization constant making \int probability(x) == 1.0, and
    *   logProbability(x) = K - error(x)
-   * i.e., K = log(K).
+   * i.e., K = log(K). The normalization constant K is assumed to *not* depend
+   * on any argument, only (possibly) on the conditional parameters.
+   * This class provides a default logNormalizationConstant() == 0.0.
    * 
    * There are four broad classes of conditionals that derive from Conditional:
    *
@@ -181,9 +183,20 @@ namespace gtsam {
     /** Mutable iterator pointing past the last parent key. */
     typename FACTOR::iterator endParents() { return asFactor().end(); }
 
+    /**
+     * Check invariants of this conditional, given the values `x`.
+     * It tests:
+     *  - evaluate >= 0.0
+     *  - evaluate(x) == conditional(x)
+     *  - exp(logProbability(x)) == evaluate(x)
+     *  - logProbability(x) == logNormalizationConstant() - error(x)
+     *
+     * @param conditional The conditional to test, as a reference to the derived type.
+     * @tparam VALUES HybridValues, or a more narrow type like DiscreteValues.
+    */
     template <class VALUES>
     static bool CheckInvariants(const DERIVEDCONDITIONAL& conditional,
-                                const VALUES& values);
+                                const VALUES& x);
 
     /// @}