From 81eb2ebf0e8ab407c01d4702e6aaa17fc51108eb Mon Sep 17 00:00:00 2001
From: Jeff Donahue <jeff.donahue@gmail.com>
Date: Sat, 30 Aug 2014 14:46:13 -0700
Subject: [PATCH] filler.hpp: add brief filler descriptions

---
 include/caffe/filler.hpp | 39 ++++++++++++++++++++++++++++-----------
 1 file changed, 28 insertions(+), 11 deletions(-)

diff --git a/include/caffe/filler.hpp b/include/caffe/filler.hpp
index a836680..136ce95 100644
--- a/include/caffe/filler.hpp
+++ b/include/caffe/filler.hpp
@@ -15,6 +15,7 @@
 
 namespace caffe {
 
+/// @brief Fills a Blob with constant or randomly-generated data.
 template <typename Dtype>
 class Filler {
  public:
@@ -26,6 +27,7 @@ class Filler {
 };  // class Filler
 
 
+/// @brief Fills a Blob with constant values @f$ x = 0 @f$.
 template <typename Dtype>
 class ConstantFiller : public Filler<Dtype> {
  public:
@@ -44,6 +46,7 @@ class ConstantFiller : public Filler<Dtype> {
   }
 };
 
+/// @brief Fills a Blob with uniformly distributed values @f$ x\sim U(a, b) @f$.
 template <typename Dtype>
 class UniformFiller : public Filler<Dtype> {
  public:
@@ -58,6 +61,7 @@ class UniformFiller : public Filler<Dtype> {
   }
 };
 
+/// @brief Fills a Blob with Gaussian-distributed values @f$ x = a @f$.
 template <typename Dtype>
 class GaussianFiller : public Filler<Dtype> {
  public:
@@ -92,6 +96,9 @@ class GaussianFiller : public Filler<Dtype> {
   shared_ptr<SyncedMemory> rand_vec_;
 };
 
+/** @brief Fills a Blob with values @f$ x \in [0, 1] @f$
+ *         such that @f$ \forall i \sum_j x_{ij} = 1 @f$.
+ */
 template <typename Dtype>
 class PositiveUnitballFiller : public Filler<Dtype> {
  public:
@@ -119,14 +126,21 @@ class PositiveUnitballFiller : public Filler<Dtype> {
   }
 };
 
-// A filler based on the paper [Bengio and Glorot 2010]: Understanding
-// the difficulty of training deep feedforward neuralnetworks, but does not
-// use the fan_out value.
-//
-// It fills the incoming matrix by randomly sampling uniform data from
-// [-scale, scale] where scale = sqrt(3 / fan_in) where fan_in is the number
-// of input nodes. You should make sure the input blob has shape (num, a, b, c)
-// where a * b * c = fan_in.
+/**
+ * @brief Fills a Blob with values @f$ x \sim U(-a, +a) @f$ where @f$ a @f$
+ *        is set inversely proportional to the number of incoming nodes.
+ *
+ * A Filler based on the paper [Bengio and Glorot 2010]: Understanding
+ * the difficulty of training deep feedforward neuralnetworks, but does not
+ * use the fan_out value.
+ *
+ * It fills the incoming matrix by randomly sampling uniform data from
+ * [-scale, scale] where scale = sqrt(3 / fan_in) where fan_in is the number
+ * of input nodes. You should make sure the input blob has shape (num, a, b, c)
+ * where a * b * c = fan_in.
+ *
+ * TODO(dox): make notation in above comment consistent with rest & use LaTeX.
+ */
 template <typename Dtype>
 class XavierFiller : public Filler<Dtype> {
  public:
@@ -144,9 +158,12 @@ class XavierFiller : public Filler<Dtype> {
 };
 
 
-// A function to get a specific filler from the specification given in
-// FillerParameter. Ideally this would be replaced by a factory pattern,
-// but we will leave it this way for now.
+/**
+ * @brief Get a specific filler from the specification given in FillerParameter.
+ *
+ * Ideally this would be replaced by a factory pattern, but we will leave it
+ * this way for now.
+ */
 template <typename Dtype>
 Filler<Dtype>* GetFiller(const FillerParameter& param) {
   const std::string& type = param.type();
-- 
2.7.4