a little more documentation for the module.register_wrapper mechanism

doc/advanced/module.txt

@@ -54,6 +54,7 @@ non-symbolic thing.
 
 Compiling with make
 -------------------
+
 Conversion from a Component graph to a ComponentInstance graph is performed by `Component.make`.
 This method traverses the Component graph in multiple passes. 
 
@@ -77,7 +78,6 @@ allocated in phase 1 with sensible values.
    single: component; External
 
 .. _external:
-
 --------
 External
 --------
@@ -91,7 +91,6 @@ WRITEME
    single: component; Member
 
 .. _member:
-
 ------
 Member
 ------
@@ -104,7 +103,6 @@ WRITEME
    single: component; Method
 
 .. _method:
-
 ------
 Method
 ------
@@ -117,13 +115,17 @@ WRITEME
    single: component; Module
 
 .. _module:
-
 ------
 Module
 ------
 
-WRITEME
-
-
+A Module instance can contain objects as attributes.
+This makes it something like a class in the way that Method is
+analogous to a function.
 
+A Module is meant to contain Components.
+Attributes which are not Components themselves must at least be transform-able
+into Components by :api:`compile.module.wrap`.  If a Module contains something
+that is not convertible into a Component, then it is not possible to compile
+that Module with ``make``.
 

theano/compile/module.py

@@ -771,7 +771,10 @@ class ComponentDict(Composite):
 
     def set(self, item, value):
         if not isinstance(value, Component):
-            raise TypeError('ComponentDict may only contain Components.', value, type(value))
+            msg = """
+            ComponentDict may only contain Components. 
+            (Hint: maybe value here needs to be wrapped, see theano.compile.module.register_wrapper.)"""
+            raise TypeError(msg, value, type(value))
         #value = value.bind(self, item)
         value.name = name_join(self.name, str(item))
         self._components[item] = value
@@ -803,6 +806,16 @@ class ComponentDict(Composite):
 __autowrappers = []
 
 def register_wrapper(condition, wrapper):
+    """
+    :type condition: function x -> bool
+
+    :param condition: this function should return True iff `wrapper` can sensibly turn x into a
+    Component.
+
+    :type wrapper: function x -> Component
+
+    :param wrapper: this function should convert `x` into an instance of a Component subclass.
+    """
     __autowrappers.append((condition, wrapper))
 
 def wrapper(x):
@@ -816,8 +829,13 @@ def wrapper(x):
 
 def wrap(x):
     """
-    Wraps x in a Component. Wrappers can be registered using
-    register_wrapper to allow wrapping more types.
+    Wraps `x` in a `Component`. Wrappers can be registered using
+    `register_wrapper` to allow wrapping more types.
+
+    It is necessary for Module attributes to be wrappable.
+    A Module with an attribute that is not wrappable as a Component, will cause
+    `Component.make` to fail.
+
     """
     w = wrapper(x)
     if w is not None: