added doc for nodes_constructed

theano/gof/graph.py

@@ -539,6 +539,7 @@ class Variable(Node):
             d["tag"] = t
         return d
 
+    #  refer to doc in nodes_constructed.
     construction_observers = []
 
     @classmethod
@@ -1448,6 +1449,30 @@ def is_in_ancestors(l_node, f_node):
 
 @contextlib.contextmanager
 def nodes_constructed():
+    """
+    A contextmanager that is used in inherit_stack_trace and keeps track
+    of all the newly created varaible nodes inside an optimization. A list
+    of new_nodes is instantiated but will be filled in a lazy manner (when
+    Variable.notify_construction_observers is called).
+
+
+    `observer` is the entity that updates the new_nodes list.
+    construction_observers is a list inside Variable class and contains
+    a list of observer functions. The observer functions inside
+    construction_observers are only called when a variable node is
+    instantiated (where Variable.notify_construction_observers is called).
+    When the observer function is called, a new variable node is added to
+    the new_nodes list.
+
+
+    Parameters
+    ----------
+    new_nodes
+        A list of all the variable nodes that are created inside the optimization.
+
+    yields
+        new_nodes list.
+    """
     new_nodes = []
 
     def observer(node):

theano/gof/opt.py

@@ -2953,13 +2953,14 @@ def copy_stack_trace(from_var, to_var):
 @contextlib.contextmanager
 def inherit_stack_trace(from_var):
     """
-    Contextmanager that copies the stack trace from one or more tensor variables to all tensor
-    variables constructed in the body.
+    Contextmanager that copies the stack trace from one or more variable nodes to all
+    variable nodes constructed in the body. new_nodes is the list of all the newly created
+    variable nodes inside an optimization that is managed by graph.nodes_constructed().
 
     Parameters
     ----------
     from_var
-        Tensor variable or list of tensor variables to copy stack traces from.
+        Variable node or a list of variable nodes to copy stack traces from.
 
     """
     with graph.nodes_constructed() as new_nodes: