More documentation

src/dataset.h

@@ -24,16 +24,35 @@
 #include <memory>
 
 namespace marian {
+
+
+/**
+ * @brief Namespace for code related to managing user data in Marian
+ */
 namespace data {
 
+/** @brief Defines a convenience type to represent an ordered collection of floating point data. */
 typedef std::vector<float> Data;
+
+/** @brief Defines a convenience type to represent a shared pointer to an ordered collection of floating point data. */
 typedef std::shared_ptr<Data> DataPtr;
 
+/** @brief Defines a convenience type to represent an ordered collection of ::DataPtr objects. */
 typedef std::vector<DataPtr> Example;
+
+/** @brief Defines a convenience type to represent a shared pointer to an ordered collection of ::DataPtr objects. */
 typedef std::shared_ptr<Example> ExamplePtr;
 
+/** @brief Defines a convenience type to represent an ordered collection of ::ExamplePtr objects. */
 typedef std::vector<ExamplePtr> Examples;
 
+/**  
+ * @brief Defines a convenience type to represent a const_iterator over the ::ExamplePtr objects 
+ *           stored in an ::Examples object.
+ */
+typedef Examples::const_iterator ExampleIterator;
+
+
 class Input {
   private:
     Shape shape_;
@@ -43,54 +62,79 @@ class Input {
     typedef Data::iterator iterator;
     typedef Data::const_iterator const_iterator;
 
+    /** @brief Constructs a new Input object with the specified Shape */
     Input(const Shape& shape)
     : shape_(shape),
       data_(new Data(shape_.totalSize(), 0.0f)) {}
 
+    /** @brief Gets an iterator pointing to the beginning of this object's ::Data */
     Data::iterator begin() {
       return data_->begin();
     }
 
+    /** @brief Gets an iterator pointing to the end of this object's ::Data */
     Data::iterator end() {
       return data_->end();
     }
 
+    /** @brief Gets a const iterator pointing to the beginning of this object's ::Data */
     Data::const_iterator begin() const {
       return data_->cbegin();
     }
 
+    /** @brief Gets a const iterator pointing to the end of this object's ::Data. */
     Data::const_iterator end() const {
       return data_->cend();
     }
 
+    /** @brief Returns a reference to this object's underlying ::Data. */
     Data& data() {
       return *data_;
     }
 
+    /** @brief Gets this object's underlying Shape. */
     Shape shape() const {
       return shape_;
     }
 
+    /** @brief Returns the number underlying values in this object's ::Data. */
     size_t size() const {
       return data_->size();
     }
 };
 
-typedef Examples::const_iterator ExampleIterator;
-
 class DataBase {
   public:
+   
+    /** @brief Returns an iterator pointing to the beginning of this object's underlying data. */
     virtual ExampleIterator begin() const = 0;
+
+    /** @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?
     virtual void shuffle() = 0;
 
+    // TODO: Marcin, what does this do?
     virtual int dim(size_t i) {
       return (*begin())->at(i)->size();
     }
 };
 
+/** @brief Defines a convenience type to represent a shared pointer to a DataBase object. */
 typedef std::shared_ptr<DataBase> DataBasePtr;
 
+/** 
+ * @brief Convenience function to construct a new DataBase object and return a shared pointer to that object.
+ *
+ * The template parameters for this function specify two main pieces of information:
+ * -# The first template parameter specifies the type of DataBase object to be constructed
+ * -# Any subsequent template parameters specify the type(s) of any arguments to that DataBase object constructor
+ *
+ * @arg args An optional list of parameters which will be passed to the DataBase constructor
+ *
+ * @return a shared pointer to a newly constructed DataBase object
+ */
 template <class Set, typename ...Args>
 DataBasePtr DataSet(Args&& ...args) {
   return DataBasePtr(new Set(args...));

src/keywords.h

@@ -35,7 +35,7 @@ namespace keywords {
    * @brief Represents a named keyword capable of storing a single value.
    *
    * This class is used to emulate <a href="https://en.wikipedia.org/wiki/Named_parameter">keyword arguments to functions</a>, 
-   *    such as those <a href="https://docs.python.org/3/tutorial/controlflow.html#keyword-arguments">found in Python</code>.
+   *    such as those <a href="https://docs.python.org/3/tutorial/controlflow.html#keyword-arguments">found in Python</a>.
    *
    * It is expected that users of this class will not explicitly create instances of this class.
    *
@@ -56,20 +56,47 @@ namespace keywords {
     public:
       typedef Value value_type;
 
+      /** 
+       * @brief Constructs a <code>Keyword</code> which will store the specified value. 
+       *
+       * @arg value The value to store in this object
+       */
       Keyword(Value value)
       : value_(value) {}
 
+      /** 
+       * @brief Constructs a <code>Keyword</code> with no specified value. 
+       *
+       * The value stored in the resulting object will be constructed using that Value's default constructor.
+       */
       Keyword()
       : value_() {}
 
+      /**
+       * @brief Constructs and returns a new <code>Keyword</code> object containing the specified value.
+       *
+       * Note: despite the conventional semantics of operator=, this method <em>does not modify</em> the current object.
+       *
+       * @return  a new <code>Keyword</code> object containing the specified value
+       */
       Keyword<key, Value> operator=(Value value) const {
         return Keyword<key, Value>(value);
       }
 
+      /**
+       * @brief Gets a const reference to the value stored in this object.
+       *
+       * @return a const reference to the value stored in this object
+       */
       const Value& operator()() const {
         return value_;
       }
 
+      /**
+       * @brief Gets the hashed integer identifier associated with this object.
+       *
+       * @return the hashed integer identifier associated with this object
+       */ 
       unsigned id() const {
         return key;
       }

src/mnist.h

@@ -34,6 +34,7 @@
 namespace marian {
 namespace data {
 
+/** @brief DataBase capable of reading <a href="http://yann.lecun.com/exdb/mnist/">MNIST</a> data. */
 class MNIST : public DataBase {
   private:
     const int IMAGE_MAGIC_NUMBER;
@@ -44,6 +45,12 @@ class MNIST : public DataBase {
   public:
 
 
+    /**
+     * @brief Constructs a DataBase using <a href="http://yann.lecun.com/exdb/mnist/">MNIST</a> data.
+     *
+     * @param featuresPath Path to file containing <a href="http://yann.lecun.com/exdb/mnist/">MNIST</a> feature values
+     * @param labelsPath   Path to file containing <a href="http://yann.lecun.com/exdb/mnist/">MNIST</a> labels
+     */
     MNIST(const std::string& featuresPath,
           const std::string& labelsPath)
     : IMAGE_MAGIC_NUMBER(2051),

src/models/feedforward.h

@@ -8,7 +8,9 @@ namespace models {
 /**
  * @brief Constructs an expression graph representing a feed-forward classifier.
  *
- * @return an expression graph representing a feed-forward classifier
+ * @param dims
+ *
+ * @return a shared pointer to the newly constructed expression graph
  */
 ExpressionGraphPtr FeedforwardClassifier(const std::vector<int>& dims) {
   using namespace keywords;