Fix comments while reading the codes. (#42)

.gitignore

@@ -33,3 +33,7 @@ lib
 dmlc-core
 cli_test
 *.pyc
+
+# Vim
+*.swp
+*.swo

include/nnvm/pass.h

@@ -14,22 +14,23 @@
 namespace nnvm {
 
 /*!
- * \brief A PassFunction is a basic "Operator on Graph"
- *  It takes a source graph
+ * \brief A PassFunction is an "Operator on Graph".
+ *  It takes a source graph and return a graph that may or may
+ *  not be the same as the input one.
  *
- *  A pass function can either change the graph structure of g,
- *  generating a new Graph, or add new attributes to the graph.
+ *  A pass function can either change the graph structure (thus,
+ *  generating a new Graph), or add new attributes to the graph.
  *
  * \param src The graph to be transformed.
  * \return The generated graph.
  */
 typedef std::function<Graph (Graph src)> PassFunction;
 
 /*!
- * \brief Apply a series of pass transformations on g.
+ * \brief Apply a series of pass transformations on the input graph.
  * \param src The graph to be transformed.
  * \param pass The name of pass to be applied.
- * \return The transformed graph
+ * \return The transformed graph.
  */
 Graph ApplyPass(Graph src,
                 const std::vector<std::string>& pass);
@@ -52,36 +53,39 @@ struct PassFunctionReg
   /*! \brief generated targets of graph attributes */
   std::vector<std::string> graph_attr_targets;
   /*!
-   * \brief set whether this pass will change graph structure.
-   * \param v the value to set
-   * \return reference to self.
+   * \brief Set whether this pass will change graph structure.
+   * \param v If true, the pass will change graph structure.
+   * \return Reference to self.
    */
   PassFunctionReg& set_change_graph(bool v) {  // NOLINT(*)
     change_graph = v;
     return *this;
   }
   /*!
-   * \brief Declare this pass require operator attribute attr_name to be available.
-   * \param attr_name Name of the attribute.
-   * \return reference to self.
+   * \brief Declare that this pass will generate the given graph attribute name
+   *        once it is applied on the graph.
+   * \param attr_name Name of the graph attribute.
+   * \return Reference to self.
    */
   PassFunctionReg& provide_graph_attr(const std::string& attr_name) {  // NOLINT(*)
     graph_attr_targets.push_back(attr_name);
     return *this;
   }
   /*!
-   * \brief declare this pass require operator attribute attr_name to be available.
+   * \brief Declare this pass requires the given operator attribute to be 
+   *        available before being applied on the graph.
    * \param attr_name Name of the attribute.
-   * \return reference to self.
+   * \return Reference to self.
    */
   PassFunctionReg& depend_op_attr(const std::string& attr_name) {  // NOLINT(*)
     op_attr_dependency.push_back(attr_name);
     return *this;
   }
   /*!
-   * \brief declare this pass require graph attribute attr_name to be available.
+   * \brief Declare this pass requires the given graph attribute to be
+   *        available before being applied on the graph.
    * \param attr_name Name of the attribute.
-   * \return reference to self.
+   * \return Reference to self.
    */
   PassFunctionReg& depend_graph_attr(const std::string& attr_name) {  // NOLINT(*)
     graph_attr_dependency.push_back(attr_name);

include/nnvm/pass_functions.h

@@ -33,7 +33,7 @@ inline Graph LoadJSON(const std::string& json_str) {
 
 /*!
  * \brief Save a graph to json, redirects to "SaveJSON" pass.
- * \param graph The to be saved.
+ * \param graph The graph to be saved as json format.
  * \return The json string.
  */
 inline std::string SaveJSON(Graph graph) {
@@ -42,23 +42,27 @@ inline std::string SaveJSON(Graph graph) {
 }
 
 /*!
- * \brief Add control flow dependencies between nodes
- *  To correctly order mutation and read to resolve
- *  write after read problem and read after write problems.
- * \param src source graph
- * \return A graph that added control flow dependencies.
+ * \brief Add control flow dependencies between nodes.
+ *
+ *  This function will enforce the correct order between
+ *  write (mutable operators) and read (immutable operators)
+ *  to sovle write-after-read and read-after-write problems.
+ *
+ * \param src The input graph.
+ * \return A graph with proper control flow dependencies added.
  */
 inline Graph OrderMutation(Graph src) {
   return ApplyPass(std::move(src), {"OrderMutation"});
 }
 
 /*!
  * \brief Infer shapes in the graph given the information.
- * \param graph source graph
- * \param shape_inputs The shapes of aruguments to the graph.
- * \param shape_attr_key The key to the node attribute that can indicate shape.
+ * \param graph The input graph.
+ * \param shape_inputs The shapes of input symbols to the graph.
+ * \param shape_attr_key The key to the node attribute that can indicate shape. This is
+ *                       the place where manual hint for shapes could be injected.
  * \return A graph with new attribute "shape" containing inferred shape of each NodeEntry.
- *  The index of ShapeVector is given by graph.indexed_graph().entry_id
+ *         The index of ShapeVector is given by graph.indexed_graph().entry_id.
  */
 inline Graph InferShape(Graph graph,
                         ShapeVector shape_inputs,
@@ -74,11 +78,12 @@ inline Graph InferShape(Graph graph,
 
 /*!
  * \brief Infer types in the graph given the information.
- * \param graph source graph
- * \param dtype_inputs The shapes of inputs to the graph.
- * \param dtype_attr_key The key to the node attribute that can indicate shape.
- * \return A graph with new attribute "shape" containing inferred shape of each NodeEntry.
- *  The index of ShapeVector is given by graph.indexed_graph().entry_id
+ * \param graph The input graph.
+ * \param dtype_inputs The types of input symbols to the graph.
+ * \param dtype_attr_key The key to the node attribute that can indicate types. This is
+ *                       the place where manual hint for types could be injected.
+ * \return A graph with new attribute "dtype" containing inferred type of each NodeEntry.
+ *         The index of ShapeVector is given by graph.indexed_graph().entry_id.
  */
 inline Graph InferType(Graph graph,
                        DTypeVector dtype_inputs,
@@ -93,10 +98,16 @@ inline Graph InferType(Graph graph,
 }
 
 /*!
- * \brief Place the devices
- * \param graph source graph
- * \param device_group_attr_key The attribute name for hinting the device group.
- * \param device_assign_map The assignment map of device
+ * \brief Place the devices for each operator in the graph.
+ *
+ *  Current device placement is quite simple. Each operator is assigned to a "group" (stored
+ *  in `device_group_attr_key` attribute). Each group is assigned to a device (stored in
+ *  `device_assign_map` attribute). Operators will be placed to the device assigned to its
+ *  group. Copy operators will be injected if cross device reference happens.
+ *
+ * \param graph The input graph.
+ * \param device_group_attr_key The attribute name for hints of device group.
+ * \param device_assign_map The assignment map of device.
  * \param device_copy_op The name of copy op to be inserted when cross device copy happened.
  * \return A graph with new attribute "device", cotaining device information of each node.
  */
@@ -112,13 +123,13 @@ inline Graph PlaceDevice(Graph graph,
 
 /*!
  * \brief Get the gradient graph whose outputs are gradients of xs wrt to ys.
- * \param graph source graph
+ * \param graph The input graph.
  * \param ys The entries we want to take gradient from.
  * \param xs The input to take gradient with respect to.
  * \param ys_out_grad The symbol for additional gradient to be propagate back to y.
- * \param aggregate_fun aggregation function applied to aggregate the inputs
+ * \param aggregate_fun Aggregation function applied to aggregate the inputs.
  * \param mirror_fun Optional mirror function to do mirror optimization and save memory.
- * \return A new graph, whose outputs corresponds to inputs of xs.
+ * \return A new graph, whose outputs correspond to inputs of xs.
  */
 inline Graph Gradient(
     Graph graph,

include/nnvm/symbolic.h

@@ -19,7 +19,13 @@
 
 namespace nnvm {
 /*!
- * \brief Symbol is used to represent the
+ * \brief Symbol is help class used to represent the operator node in Graph.
+ * 
+ *  Symbol acts as an interface for building graphs from different components
+ *  like Variable, Functor and Group. Symbol is also exported to python front-end
+ *  (while Graph is not) to enable quick test and deployment. Conceptually,
+ *  symbol is the final operation of a graph and thus including all the information
+ *  required (the graph) to evaluate its output value.
  */
 class Symbol {
  public:
@@ -47,42 +53,46 @@ class Symbol {
   std::vector<NodeEntry> outputs;
 
   /*!
-   * \brief copy the symbol
-   * \return a deep copy of the symbolic graph.
+   * \brief Copy the symbol.
+   * \return A deep copy of this symbol.
    */
   Symbol Copy() const;
   /*!
-   * \brief print the symbol info to output stream.
-   * \param os the output stream we like to print to
+   * \brief Print the symbol info to output stream.
+   * \param os The output stream to print to.
    */
   void Print(std::ostream &os) const; // NOLINT(*)
   /*!
-   * \brief get the index th element from the returned tuple.
-   * \param index index of multi output
-   * \return the symbol corresponds to the indexed element.
+   * \brief Get the index-th element from the returned tuple.
+   * \param index Index of multi output.
+   * \return The symbol corresponds to the indexed element.
    */
   Symbol operator[] (size_t index) const;
   /*!
-   * \brief List the input variable nodes
-   * \param option The options to list the arguments.
+   * \brief List the input variable nodes.
+   *
+   *  The order of the returned list is the same as the order of the input list to `operator()`.
    *
-   * The position of the returned list also corresponds to calling position in operator()
-   * \return the arguments list of this symbol, they can be either named or unnamed (empty string).
+   * \param option The options to list the arguments.
+   * \return The arguments list of this symbol, they can be either named or unnamed (empty string).
    * \sa ListInputOption
    */
   std::vector<NodePtr> ListInputs(ListInputOption option) const;
   /*!
    * \brief List the input names.
-   * \param option The options to list the arguments.
    *
-   * The position of the returned list also corresponds to calling position in operator()
-   * \return the arguments list of this symbol, they can be either named or unnamed (empty string).
+   *  The order of the returned list is the same as the order of the input list to `operator()`.
+   *
+   * \param option The options to list the arguments.
+   * \return The arguments list of this symbol, they can be either named or unnamed (empty string).
    * \sa ListInputOption
    */
   std::vector<std::string> ListInputNames(ListInputOption option) const;
   /*!
    * \brief List the names of outputs for this symbol.
-   *  For normal operators, it is usually symbol node name + "_output"
+   *
+   *  For normal operators, it is usually symbol node name + "_output".
+   *
    * \return get the descriptions of outputs for this symbol.
    */
   std::vector<std::string> ListOutputNames() const;
@@ -92,83 +102,90 @@ class Symbol {
    *
    * The rest of the symbols will remain the same name.
    *
-   * \param args positional arguments
-   * \param kwargs keyword arguments for the symbol
-   * \param name name of returned symbol.
+   * \param args Positional arguments.
+   * \param kwargs Keyword arguments for the symbol.
+   * \param name Name of returned symbol.
    */
   void Compose(const array_view<const Symbol*>& args,
                const std::unordered_map<std::string, const Symbol*>& kwargs,
                const std::string& name);
   /*!
    * \brief Apply the symbol as a function, compose with arguments
-   * This is equivalent to Copy then Compose.
-   * \param args positional arguments for the symbol
-   * \param kwargs keyword arguments for the symbol
-   * \param name name of returned symbol.
-   * \return a new Symbol which is the composition of current symbol with its arguments
+   *
+   *  This is equivalent to Copy then Compose.
+   *
+   * \param args Positional arguments for the symbol.
+   * \param kwargs Keyword arguments for the symbol.
+   * \param name Name of returned symbol.
+   * \return A new Symbol which is the composition of current symbol with its arguments.
    */
   Symbol operator () (const array_view<const Symbol*>& args,
                       const std::unordered_map<std::string, const Symbol*>& kwargs,
                       const std::string& name) const;
   /*!
-   * \brief Add control flow depenencies to operators involved in symbols.
-   *  For grouped sybmbol, an error will be raised.
-   *  This mutate current symbolic Node.
+   * \brief Add control flow depenencies to the operators in symbols.
+   *
+   *  For grouped symbol, an error will be raised. This mutates current symbolic Node.
    *
    * \param src The symbols to depend on.
    */
   void AddControlDeps(const Symbol& src);
   /*
    * \brief Get all the internal nodes of the symbol.
    * \return symbol A new symbol whose output contains all the outputs of the symbols
-   *  Including input variables and intermediate outputs.
+   *                including input variables and intermediate outputs.
    */
   Symbol GetInternals() const;
   /*!
-   * \brief set additional attributes to current node.
+   * \brief Set additional attributes to current node.
+   *
    *  This only works for symbol with outputs from single operators.
-   *  For grouped sybmbol, an error will be raised.
+   *  For grouped symbol, an error will be raised.
    *
-   *  This function mutate the node's symbol and is not recommended.
+   *  This function mutates the node's symbol and is not recommended.
    *
    * \param attrs The attributes to set.
    */
   void SetAttrs(const std::vector<std::pair<std::string, std::string> >& attrs);
   /*!
    * \brief Get attributes from the symbol.
+   *
    *  This only works for symbol with outputs from single operators.
-   *  For grouped sybmbol, an error will be raised.
+   *  For grouped symbol, an error will be raised.
+   *
    * \param key Key of the attribute. When key == "name", it returns the name attirbute.
-   * \param out the output value of the attribute.
-   * \return true if the attribute exists, false if the attribute do not exist.
+   * \param out The output value of the attribute.
+   * \return true If the attribute exists, false if the attribute does not exist.
    */
   bool GetAttr(const std::string& key, std::string* out) const;
   /*!
    * \brief Get attribute dictionary from the symbol.
-   *  For grouped sybmbol, an error will be raised.
-   * \param option If recursive is set, the attributes of all children are retrieved,
-   *   The name of symbol will be pre-pended to each key.
+   *
+   *  For grouped symbol, an error will be raised.
+   *
+   * \param option If recursive flag is set, the attributes of all children are retrieved.
+   *               The name of symbol will be pre-pended to each key.
    * \return The created attribute.
    */
   std::unordered_map<std::string, std::string> ListAttrs(ListAttrOption option) const;
   /*!
-   * \brief create symbolic functor(AtomicSymbol) by given operator and attributes.
+   * \brief Create symbolic functor(AtomicSymbol) by given operator and attributes.
    * \param op The operator.
    * \param attrs The additional attributes.
    * \return Symbol that can be used to call compose further.
    */
   static Symbol CreateFunctor(const Op* op,
                               std::unordered_map<std::string, std::string> attrs);
   /*!
-   * \brief create variable symbol node
-   * \param name name of the variable
-   * \return the new variable
+   * \brief Create symbol node representing variable.
+   * \param name Name of the variable.
+   * \return The symbol.
    */
   static Symbol CreateVariable(const std::string& name);
   /*!
-   * \brief create equivalence of symbol by grouping the symbols together
-   * \param symbols list of symbols
-   * \return the grouped symbol
+   * \brief Create equivalence of symbol by grouping the symbols together.
+   * \param symbols A list of symbols to be grouped.
+   * \return The grouped symbol.
    */
   static Symbol CreateGroup(const std::vector<Symbol>& symbols);
 };