Some documentation improvements

[libdai.git] / include / dai / bbp.h

diff --git a/include/dai/bbp.h b/include/dai/bbp.h
index c361afe..efddc6c 100644 (file)
--- a/include/dai/bbp.h
+++ b/include/dai/bbp.h
@@ -65,7 +65,7 @@ class BBP {
         BP_dual _bp_dual;
         /// Pointer to the factor graph
         const FactorGraph *_fg;
         BP_dual _bp_dual;
         /// Pointer to the factor graph
         const FactorGraph *_fg;

-        /// Pointer to the approximate inference algorithm
+        /// Pointer to the approximate inference algorithm (currently, only BP objects are supported)

         const InfAlg *_ia;
     //@}
 
         const InfAlg *_ia;
     //@}
 


@@ -258,7 +258,10 @@ class BBP {
     public:
     /// \name Constructors/destructors
     //@{
     public:
     /// \name Constructors/destructors
     //@{

-        /// Construct from a InfAlg \a ia and a PropertySet \a opts
+        /// Construct BBP object from a InfAlg \a ia and a PropertySet \a opts
+        /** \param ia should be a BP object or something compatible
+         *  \param opts Parameters @see Properties
+         */

         BBP( const InfAlg *ia, const PropertySet &opts ) : _bp_dual(ia), _fg(&(ia->fg())), _ia(ia) {
             props.set(opts);
         }
         BBP( const InfAlg *ia, const PropertySet &opts ) : _bp_dual(ia), _fg(&(ia->fg())), _ia(ia) {
             props.set(opts);
         }


@@ -327,18 +330,24 @@ class BBP {
     //@}
 
     public:
     //@}
 
     public:

-        /// Parameters of this algorithm
+        /// Parameters for BBP

         /* PROPERTIES(props,BBP) {
         /* PROPERTIES(props,BBP) {

-           /// Enumeration of possible update schedules
+           /// \brief Enumeration of possible update schedules
+           /// - SEQ_FIX fixed sequential updates
+           /// - SEQ_MAX maximum residual updates (inspired by [\ref EMK06])
+           /// - SEQ_BP_REV schedule used by BP, but reversed
+           /// - SEQ_BP_FWD schedule used by BP
+           /// - PAR parallel updates

            DAI_ENUM(UpdateType,SEQ_FIX,SEQ_MAX,SEQ_BP_REV,SEQ_BP_FWD,PAR);
 
            DAI_ENUM(UpdateType,SEQ_FIX,SEQ_MAX,SEQ_BP_REV,SEQ_BP_FWD,PAR);
 

-           /// Verbosity
+           /// Verbosity (amount of output sent to stderr)

            size_t verbose;
 
            /// Maximum number of iterations
            size_t maxiter;
 
            size_t verbose;
 
            /// Maximum number of iterations
            size_t maxiter;
 

-           /// Tolerance (not used for updates = SEQ_BP_REV, SEQ_BP_FWD)
+           /// Tolerance for convergence test
+           /// \note Not used for updates = SEQ_BP_REV, SEQ_BP_FWD

            Real tol;
 
            /// Damping constant (0 for none); damping = 1 - lambda where lambda is the damping constant used in [\ref EaG09]
            Real tol;
 
            /// Damping constant (0 for none); damping = 1 - lambda where lambda is the damping constant used in [\ref EaG09]


@@ -356,12 +365,21 @@ class BBP {
 */
         struct Properties {
             /// Enumeration of possible update schedules
 */
         struct Properties {
             /// Enumeration of possible update schedules

+            /** The following update schedules are defined:
+             *  - SEQ_FIX fixed sequential updates
+             *  - SEQ_MAX maximum residual updates (inspired by [\ref EMK06])
+             *  - SEQ_BP_REV schedule used by BP, but reversed
+             *  - SEQ_BP_FWD schedule used by BP
+             *  - PAR parallel updates
+             */

             DAI_ENUM(UpdateType,SEQ_FIX,SEQ_MAX,SEQ_BP_REV,SEQ_BP_FWD,PAR);
             DAI_ENUM(UpdateType,SEQ_FIX,SEQ_MAX,SEQ_BP_REV,SEQ_BP_FWD,PAR);

-            /// Verbosity
+            /// Verbosity (amount of output sent to stderr)

             size_t verbose;
             /// Maximum number of iterations
             size_t maxiter;
             size_t verbose;
             /// Maximum number of iterations
             size_t maxiter;

-            /// Tolerance (not used for updates = SEQ_BP_REV, SEQ_BP_FWD)
+            /// Tolerance for convergence test
+            /** \note Not used for updates = SEQ_BP_REV, SEQ_BP_FWD
+             */

             Real tol;
             /// Damping constant (0 for none); damping = 1 - lambda where lambda is the damping constant used in [\ref EaG09]
             Real damping;
             Real tol;
             /// Damping constant (0 for none); damping = 1 - lambda where lambda is the damping constant used in [\ref EaG09]
             Real damping;


@@ -369,6 +387,9 @@ class BBP {
             UpdateType updates;
 
             /// Set members from PropertySet
             UpdateType updates;
 
             /// Set members from PropertySet

+            /** \throw UNKNOWN_PROPERTY_TYPE if a Property key is not recognized
+             *  \throw NOT_ALL_PROPERTIES_SPECIFIED if an expected Property is missing
+             */

             void set(const PropertySet &opts);
             /// Get members into PropertySet
             PropertySet get() const;
             void set(const PropertySet &opts);
             /// Get members into PropertySet
             PropertySet get() const;