From a92349d96da553e235e55d55a999bb1cd9fb9371 Mon Sep 17 00:00:00 2001
From: Lane Schwartz <dowobeha@gmail.com>
Date: Wed, 28 Sep 2016 13:26:31 -0500
Subject: [PATCH] Add more comments

---
 Doxyfile.in              |  2 +-
 src/chainable.h          | 18 +++++++++++++++---
 src/dataset.h            | 16 ++++++++++++++--
 src/definitions.h        | 10 ++++++----
 src/models/feedforward.h |  7 ++++++-
 5 files changed, 42 insertions(+), 11 deletions(-)

diff --git a/Doxyfile.in b/Doxyfile.in
index e82982ff..521969a2 100644
--- a/Doxyfile.in
+++ b/Doxyfile.in
@@ -769,7 +769,7 @@ FILE_PATTERNS          =
 # be searched for input files as well.
 # The default value is: NO.
 
-RECURSIVE              = NO
+RECURSIVE              = YES
 
 # The EXCLUDE tag can be used to specify files and/or directories that should be
 # excluded from the INPUT source files. This way you can easily exclude a
diff --git a/src/chainable.h b/src/chainable.h
index 9d9e86c2..f8bd11a5 100644
--- a/src/chainable.h
+++ b/src/chainable.h
@@ -26,6 +26,9 @@
 
 #include "exception.h"
 
+/**
+ * @brief Parent namespace for the Marian project
+ */ 
 namespace marian {
 
 template <class DataType>
@@ -63,11 +66,20 @@ struct Chainable {
 // XXX Marcin, is ChainableStack the most appropriate name?
 //     AFAIK, this is never used as a FILO data structure.
 //     If so, perhaps "Tape" or "ChainLinks" or "ChainableList" might be more apropos?
-//
-//     Naumann (2012) uses "tape" to refer to this data structure.
-//     -- The Art of Differentiating Computer Programs: An Introduction to Algorithmic Differentiation, Naumann (2012)
+/**
+ * @brief Defines a convenience type to represent an ordered collection items.
+ *
+ * Conceptually, the items in this collection are pointers to nodes in an expression graph.
+ *
+ * Naumann (2012) uses "tape" to refer to this data structure.
+ * -- The Art of Differentiating Computer Programs: An Introduction to Algorithmic Differentiation, Naumann (2012)
+ */
 typedef std::vector<Chainable<Tensor>*> ChainableStack;
+
+/** @brief Defines a convenience type to represent a shared pointer to a ChainableStack. */
 typedef std::shared_ptr<ChainableStack> ChainableStackPtr;
+
+/** @brief Defines a convenience type to represent a shared pointer to a Chainable<Tensor> object. */
 typedef std::shared_ptr<Chainable<Tensor>> ChainPtr;
 
 
diff --git a/src/dataset.h b/src/dataset.h
index 0d36463d..20b3919d 100644
--- a/src/dataset.h
+++ b/src/dataset.h
@@ -112,10 +112,22 @@ class DataBase {
     /** @brief Returns an iterator pointing to the end of this object's underlying data. */
     virtual ExampleIterator end() const = 0;
     
-    // TODO: Marcin, what does this do?
+    /** @brief Randomly shuffles the elements of this object's underlying data. */
     virtual void shuffle() = 0;
 
-    // TODO: Marcin, what does this do?
+    /** 
+     * @brief Returns the size of the <em>i</em>-th dimension of the data.
+     *
+     * When an individual data point from this DataSet is used in the construction of an ExpressionGraph,
+     *   the value returned by this method can be interpreted as the size of the <em>i</em>-th input to the graph.
+     *
+     * For example, given a DataBase of MNIST data points.
+     * Each such data point contains 784 values (representing the pixel values for each of 784 pixels),
+     * and a label consisting of one of 10 labels.
+     * If the labels are interpreted as a one-hot vector of length 10,
+     * then dim(0) would return 784,
+     * and dim(1) would return 10.
+     */
     virtual int dim(size_t i) {
       return (*begin())->at(i)->size();
     }
diff --git a/src/definitions.h b/src/definitions.h
index dffacbd5..87b790e8 100644
--- a/src/definitions.h
+++ b/src/definitions.h
@@ -152,10 +152,12 @@ namespace marian {
   class RunBase;
   typedef std::shared_ptr<RunBase> RunBasePtr;
 
-  // Define a set of keywords.
-  //
-  // Each invocation of the <code>KEY()</code> macro below
-  //    will result in the creation of an instance of the <code>Keyword</code> class.
+  /** 
+   * @brief Defines a set of keywords.
+   *
+   * Each invocation of the KEY(name, value_type) macro
+   *    will result in the creation of an instance of the Keyword class.
+   */
   namespace keywords {
     KEY(axis, int)
     KEY(name, std::string)
diff --git a/src/models/feedforward.h b/src/models/feedforward.h
index d65adcb9..ff047d1e 100644
--- a/src/models/feedforward.h
+++ b/src/models/feedforward.h
@@ -3,12 +3,16 @@
 #include "expression_graph.h"
 
 namespace marian {
+
+/**
+ * @brief Namespace for code related to managing models in Marian
+ */
 namespace models {
 
 /**
  * @brief Constructs an expression graph representing a feed-forward classifier.
  *
- * @param dims
+ * @param dims number of nodes in each layer of the feed-forward classifier
  *
  * @return a shared pointer to the newly constructed expression graph
  */
@@ -21,6 +25,7 @@ ExpressionGraphPtr FeedforwardClassifier(const std::vector<int>& dims) {
   std::cerr << std::endl;
   boost::timer::cpu_timer timer;
 
+  // Construct a shared pointer to an empty expression graph
   ExpressionGraphPtr g(new ExpressionGraph());
   auto x = named(g->input(shape={whatevs, dims.front()}), "x");
   auto y = named(g->input(shape={whatevs, dims.back()}), "y");