made all the groups

src/limbo/kernel.hpp

 #ifndef LIMBO_KERNEL_HPP
 #define LIMBO_KERNEL_HPP
 
+///@defgroup kernel
+///@defgroup kernel_defaults
+
 #include <limbo/kernel/exp.hpp>
 #include <limbo/kernel/matern_five_halfs.hpp>
 #include <limbo/kernel/matern_three_halfs.hpp>

src/limbo/kernel/exp.hpp

@@ -8,11 +8,13 @@
 namespace limbo {
     namespace defaults {
         struct kernel_exp {
-          /// \ingroup defaults
+            /// @ingroup kernel_defaults
             BO_PARAM(double, sigma, 1);
         };
     }
     namespace kernel {
+        /// @ingroup kernel
+        /// Exponential kernel (TODO: formula)
         template <typename Params>
         struct Exp {
             Exp(size_t dim = 1) {}

src/limbo/kernel/matern_five_halfs.hpp

@@ -8,13 +8,19 @@
 namespace limbo {
     namespace defaults {
         struct kernel_maternfivehalfs {
-          /// \ingroup defaults
+            /// @ingroup kernel_defaults
             BO_PARAM(double, sigma, 1);
-            /// \ingroup defaults
+            /// @ingroup kernel_defaults
             BO_PARAM(double, l, 1);
         };
     }
     namespace kernel {
+        /// @ingroup kernel
+        /// Matern kernel (TODO: formula)
+        ///
+        /// Parameters:
+        /// - ``double sigma``
+        /// - ``double l``
         template <typename Params>
         struct MaternFiveHalfs {
             MaternFiveHalfs(size_t dim = 1) {}

src/limbo/kernel/matern_three_halfs.hpp

@@ -8,13 +8,19 @@
 namespace limbo {
     namespace defaults {
         struct kernel_maternthreehalfs {
-          /// \ingroup defaults
+            /// @ingroup kernel_defaults
             BO_PARAM(double, sigma, 1);
-            /// \ingroup defaults
+            /// @ingroup kernel_defaults
             BO_PARAM(double, l, 1);
         };
     }
     namespace kernel {
+        /// @ingroup kernel
+        /// Matern 3/2 kernel (TODO: formula)
+        ///
+        /// Parameters:
+        /// - ``double sigma``
+        /// - ``double l``
         template <typename Params>
         struct MaternThreeHalfs {
             MaternThreeHalfs(size_t dim = 1) {}

src/limbo/kernel/squared_exp_ard.hpp

@@ -2,16 +2,30 @@
 #define LIMBO_KERNEL_SQUARED_EXP_ARD_HPP
 
 #include <Eigen/Core>
+/*\rst
+Squared exponential covariance function with automatic relevance detection (to be used with a likelihood optimizer)
+Computes the squared exponential covariance like this:
 
+.. math::
+
+  k_{SE}(x, y) := \alpha^2 \exp(-\frac{1}{2}(x-y)^T\Lambda^{-1}(x-y)),
+
+with :math:`\Lambda = diag(l_1^2, \dots, l_n^2)` being the characteristic length scales and :math:`\alpha\f$` describing the variability of the latent function. The parameters :math:`l_1^2, \dots, l_n^2, \alpha` are expected in this order in the parameter array.
+\endrst
+*/
 namespace limbo {
     namespace kernel {
-        /** Squared exponential covariance function with automatic relevance detection.
-        * Computes the squared exponential covariance
-        * \f$k_{SE}(x, y) := \alpha^2 \exp(-\frac{1}{2}(x-y)^T\Lambda^{-1}(x-y))\f$,
-        * with \f$\Lambda = diag(l_1^2, \dots, l_n^2)\f$ being the characteristic
-        * length scales and \f$\alpha\f$ describing the variability of the latent
-        * function. The parameters \f$l_1^2, \dots, l_n^2, \alpha\f$ are expected
-        * in this order in the parameter array.
+        /**
+        @ingroup kernel
+        \rst
+        Squared exponential covariance function with automatic relevance detection (to be used with a likelihood optimizer)
+        Computes the squared exponential covariance like this:
+
+        .. math::
+            k_{SE}(x, y) := \alpha^2 \exp(-\frac{1}{2}(x-y)^T\Lambda^{-1}(x-y)),
+
+        with :math:`\Lambda = diag(l_1^2, \dots, l_n^2)` being the characteristic length scales and :math:`\alpha` describing the variability of the latent function. The parameters :math:`l_1^2, \dots, l_n^2, \alpha` are expected in this order in the parameter array.
+        \endrst
         */
         template <typename Params>
         struct SquaredExpARD {

src/limbo/mean.hpp

 #ifndef LIMBO_MEAN_HPP
 #define LIMBO_MEAN_HPP
 
+///@defgroup mean
+///@defgroup mean_defaults
+
 #include <limbo/mean/constant.hpp>
 #include <limbo/mean/data.hpp>
 #include <limbo/mean/function_ard.hpp>

src/limbo/model.hpp

 #ifndef LIMBO_MODEL_HPP
 #define LIMBO_MODEL_HPP
 
+///@defgroup model_opt
+///@defgroup model_opt_defaults
+
 #include <limbo/model/gp.hpp>
 #include <limbo/model/gp/kernel_lf_opt.hpp>
 #include <limbo/model/gp/kernel_mean_lf_opt.hpp>

src/limbo/model/gp.hpp

@@ -14,30 +14,22 @@
 
 namespace limbo {
     namespace model {
-
-
-      /**
-      \rst
-      A classic Gaussian process.
-      It is parametrized by:
-        - The :ref:`Params <params-guide>`
-        - a mean function
-        - [optionnal] an optimizer for the hyper-parameters
-
-        .. doxygenstruct:: limbo::defaults::acqui_ucb
-           :members:
-           :undoc-members:
-        \endrst
-        */
+        /// @ingroup model
+        /// A classic Gaussian process.
+        /// It is parametrized by:
+        /// - a mean function
+        /// - [optionnal] an optimizer for the hyper-parameters
         template <typename Params, typename KernelFunction, typename MeanFunction, class HyperParamsOptimizer = gp::NoLFOpt<Params>>
         class GP {
         public:
+            /// useful because the model might be created before knowing anything about the process
             GP() : _dim_in(-1), _dim_out(-1) {}
 
-            // useful because the model might be created  before having samples
+            /// useful because the model might be created  before having samples
             GP(int dim_in, int dim_out)
                 : _dim_in(dim_in), _dim_out(dim_out), _kernel_function(dim_in), _mean_function(dim_out) {}
 
+            /// Compute the GP from samples, observation, noise. [optionnal: blacklisted samples]. This call needs to be explicit!
             void compute(const std::vector<Eigen::VectorXd>& samples,
                 const std::vector<Eigen::VectorXd>& observations, double noise,
                 const std::vector<Eigen::VectorXd>& bl_samples = std::vector<Eigen::VectorXd>())
@@ -76,7 +68,11 @@ namespace limbo {
                 HyperParamsOptimizer()(*this);
             }
 
-            // return mu, sigma (unormaliz)
+            /**
+             \rst
+             return :math:`mu`, :math:`sigma` (unormalized). If there is no sample, return the value according to the mean function. Using this method instead of separate calls to mu() and sigma() is more efficient because some computations are shared between mu() and sigma().
+             \endrst
+            */
             std::tuple<Eigen::VectorXd, double> query(const Eigen::VectorXd& v) const
             {
                 if (_samples.size() == 0 && _bl_samples.size() == 0)
@@ -91,6 +87,11 @@ namespace limbo {
                 return std::make_tuple(_mu(v, k), _sigma(v, _compute_k_bl(v, k)));
             }
 
+            /**
+             \rst
+             return :math:`mu` (unormalized). If there is no sample, return the value according to the mean function.
+             \endrst
+            */
             Eigen::VectorXd mu(const Eigen::VectorXd& v) const
             {
                 if (_samples.size() == 0)
@@ -98,6 +99,11 @@ namespace limbo {
                 return _mu(v, _compute_k(v));
             }
 
+            /**
+             \rst
+             return :math:`sigma` (unormalized). If there is no sample, return the value according to the mean function.
+             \endrst
+            */
             double sigma(const Eigen::VectorXd& v) const
             {
                 if (_samples.size() == 0 && _bl_samples.size() == 0)
@@ -105,12 +111,14 @@ namespace limbo {
                 return _sigma(v, _compute_k_bl(v, _compute_k(v)));
             }
 
+            /// return the number of dimensions of the input
             int dim_in() const
             {
                 assert(_dim_in != -1); // need to compute first !
                 return _dim_in;
             }
 
+            /// return the number of dimensions of the output
             int dim_out() const
             {
                 assert(_dim_out != -1); // need to compute first !
@@ -125,6 +133,7 @@ namespace limbo {
 
             MeanFunction& mean_function() { return _mean_function; }
 
+            /// return the maximum observation (only call this if the output of the GP is of dimension 1)
             Eigen::VectorXd max_observation() const
             {
                 if (_observations.cols() > 1)
@@ -133,6 +142,7 @@ namespace limbo {
                 return _observations.maxCoeff();
             }
 
+            /// return the mean observation (only call this if the output of the GP is of dimension 1)
             Eigen::VectorXd mean_observation() const
             {
                 // TO-DO: Check if _dim_out is correct?!
@@ -144,10 +154,13 @@ namespace limbo {
 
             const Eigen::MatrixXd& obs_mean() const { return _obs_mean; }
 
+            /// return the number of samples used to compute the GP
             int nb_samples() const { return _samples.size(); }
 
+            /// return the number of blacklisted samples used to compute the GP
             int nb_bl_samples() const { return _bl_samples.size(); }
 
+            /// update the GP
             void update()
             {
                 this->_compute_obs_mean(); // ORDER MATTERS

src/limbo/model/gp/kernel_lf_opt.hpp

@@ -10,6 +10,8 @@
 namespace limbo {
     namespace model {
         namespace gp {
+            ///@ingroup model_opt
+            ///optimize the likelihood of the kernel only
             template <typename Params, typename Optimizer = opt::ParallelRepeater<Params, opt::Rprop<Params>>>
             struct KernelLFOpt {
             public:

src/limbo/model/gp/kernel_mean_lf_opt.hpp

@@ -10,6 +10,8 @@
 namespace limbo {
     namespace model {
         namespace gp {
+            ///@ingroup model_opt
+            ///optimize the likelihood of both the kernel and the mean (try to align the mean function)
             template <typename Params, typename Optimizer = opt::ParallelRepeater<Params, opt::Rprop<Params>>>
             struct KernelMeanLFOpt {
             public:

src/limbo/model/gp/mean_lf_opt.hpp

@@ -10,6 +10,8 @@
 namespace limbo {
     namespace model {
         namespace gp {
+            ///@ingroup model_opt
+            ///optimize the likelihood of the mean only (try to align the mean function)
             template <typename Params, typename Optimizer = opt::ParallelRepeater<Params, opt::Rprop<Params>>>
             struct MeanLFOpt {
             public:

src/limbo/model/gp/no_lf_opt.hpp

@@ -4,6 +4,8 @@
 namespace limbo {
     namespace model {
         namespace gp {
+            ///@ingroup model_opt
+            ///do not optimize anything
             template <typename Params>
             struct NoLFOpt {
                 template <typename GP>

src/limbo/stat.hpp

 #ifndef LIMBO_STAT_HPP
 #define LIMBO_STAT_HPP
 
+///@defgroup stat
+///@defgroup stat_defaults
+
 #include <limbo/stat/best_aggregated_observations.hpp>
 #include <limbo/stat/best_observations.hpp>
 #include <limbo/stat/best_samples.hpp>

src/limbo/stat/aggregated_observations.hpp

@@ -5,6 +5,10 @@
 
 namespace limbo {
     namespace stat {
+        ///@ingroup stat
+        /// TODO fallocati
+        ///Write all the observations
+        ///filename: `aggregated_observations.dat`
         template <typename Params>
         struct AggregatedObservations : public StatBase<Params> {
             template <typename BO, typename AggregatorFunction>

src/limbo/stat/best_aggregated_observations.hpp

@@ -5,6 +5,10 @@
 
 namespace limbo {
     namespace stat {
+        ///@ingroup stat
+        /// TODO fallocati
+        /// Write the best observation at each iteration
+        /// filename: `best_aggregated_observations.dat`
         template <typename Params>
         struct BestAggregatedObservations : public StatBase<Params> {
             template <typename BO, typename AggregatorFunction>

src/limbo/stat/best_observations.hpp

@@ -5,6 +5,9 @@
 
 namespace limbo {
     namespace stat {
+        ///@ingroup stat
+        /// Write the best observation so far
+        ///filename: `best_observations.dat"`
         template <typename Params>
         struct BestObservations : public StatBase<Params> {
             template <typename BO, typename AggregatorFunction>

src/limbo/stat/best_samples.hpp

@@ -5,6 +5,8 @@
 
 namespace limbo {
     namespace stat {
+        ///@ingroup stat
+        ///filename: `best_samples.dat`
         template <typename Params>
         struct BestSamples : public StatBase<Params> {
             template <typename BO, typename AggregatorFunction>

src/limbo/stat/bl_samples.hpp

@@ -5,6 +5,9 @@
 
 namespace limbo {
     namespace stat {
+        ///@ingroup stat
+        /// blacklisted samples
+        ///filename: `bl_samples.dat`
         template <typename Params>
         struct BlSamples : public StatBase<Params> {
             template <typename BO, typename AggregatorFunction>

src/limbo/stat/console_summary.hpp

@@ -5,6 +5,8 @@
 
 namespace limbo {
     namespace stat {
+        ///@ingroup stat
+        ///write the status of the algorithm on the terminal
         template <typename Params>
         struct ConsoleSummary : public StatBase<Params> {
             template <typename BO, typename AggregatorFunction>

src/limbo/stat/gp_acquisitions.hpp

@@ -7,6 +7,8 @@
 
 namespace limbo {
     namespace stat {
+        ///@ingroup stat
+        ///filename: `gp_acquisitions.dat`
         template <typename Params>
         struct GPAcquisitions : public StatBase<Params> {
             template <typename BO, typename AggregatorFunction>