Updated doc for function to explain the use of implicit inputs

doc/topics/function.txt

@@ -36,7 +36,7 @@ The ``inputs`` argument to ``theano.function`` is a list, containing the ``Varia
 
 .. class:: In
 
-   .. method:: __init__(variable, name=None, value=None, update=None, mutable=False)
+   .. method:: __init__(variable, name=None, value=None, update=None, mutable=False, strict=False, autoname=True, implicit=None)
 
       ``variable``: a Variable instance. This will be assigned a value
       before running the function, not computed from its owner.
@@ -46,8 +46,12 @@ The ``inputs`` argument to ``theano.function`` is a list, containing the ``Varia
       can be set by ``kwarg``, and its value can be accessed by
       ``self.<name>``. The default value is ``None``.
 
-      ``value``: literal or Container. This is the default value of
-      the Input. The default value of this parameter is ``None``
+      ``value``: literal or ``Container``. The initial/default value for this
+        input. If update is`` None``, this input acts just like
+        an argument with a default value in Python. If update is not ``None``,
+        changes to this
+        value will "stick around", whether due to an update or a user's
+        explicit action.
 
       ``update``: Variable instance. This expression Variable will
       replace ``value`` after each function call. The default value is
@@ -57,11 +61,32 @@ The ``inputs`` argument to ``theano.function`` is a list, containing the ``Varia
       compiled function to modify the Python object being used as the
       default value. The default value is ``False``.
 
+      ``strict``: Bool (default: ``False`` ). ``True`` means that the value 
+      you pass for this input must have exactly the right type. Otherwise, it
+      may be cast automatically to the proper type.
+
       ``autoname``: Bool. If set to ``True``, if ``name`` is ``None`` and
       the Variable has a name, it will be taken as the input's
       name. If autoname is set to ``False``, the name is the exact
       value passed as the name parameter (possibly ``None``).
 
+      ``implicit``: Bool or ``None`` (default: ``None``)
+        ``True``: This input is implicit in the sense that the user is not allowed
+            to provide a value for it. Requires ``value`` to be set. Setting an
+            input as implicit allows Theano to directly share containers when
+            ``value`` is an existing container.
+        ``False``: The user can provide a value for this input. In this case,
+            containers will not be shared (to avoid accidentally overwriting a
+            container's content with an input value provided by the user).
+            This means a function will create its own container, and will copy in
+            it the content of ``value`` at call time when ``value`` is a container.
+            Updates (if ``update`` is not None) will be stored into the ``value``
+            container and not in the function container (which will be filled
+            with ``None`` instead, to make sure noone tries to use it by mistake).
+        ``None``: Automatically choose between ``True`` or ``False`` depending on the
+            situation. It will be set to ``False`` in all cases except if 'value'
+            is a container (so that it can be shared by default).
+
 
 Value: initial and default values
 ---------------------------------
@@ -136,6 +161,37 @@ Theano's Module system uses this mechanism to share storage between Methods.
 The container being shared doesn't have to correspond to the same Variable in both functions, 
 but that's usually how this mechanism is used.
 
+Note that when an input's ``value`` parameter is a shared container, this
+input is considered as implicit by default. This means it cannot be set by the
+user.
+If ``implicit`` is manually set to ``False``, then it can be set by the user,
+but the container will not directly be shared: instead, the content of the
+container will be copied at call time into a separate container. However,
+updates will be performed in the container given by ``value``. The behavior
+in such situations may not be obvious, and thus is it advised not to set
+``implicit`` to ``False`` when ``value`` is a shared container, unless you
+understand what it means.
+The following code illustrates this.
+
+>>> dec(1, 0)   # Try to manually set an implicit input
+<type 'exceptions.TypeError'>: Tried to provide value for implicit input: s
+>>> dec = function([x, In(s, update=(s-x), value=inc.container[s], implicit=False)], [])
+>>> print dec[s] # dec has its own container for s, not yet filled
+None
+>>> inc[s] = 2
+>>> dec(1)
+[]
+>>> print inc[s]    # Calling dec did decrease the value in inc's container
+1.0
+>>> print dec[s]    # Set back to None instead of storing the update
+None
+>>> dec(1, 0)       # Update inc[s] with 0 - 1 = -1
+[]
+>>> print inc[s]
+-1.0
+>>> print dec[s]    # Still set back to None
+None
+
 Input Argument Restrictions
 ---------------------------
 
@@ -168,8 +224,8 @@ instance explicitly with the ``autoname`` flag set to False.
 Access to function values and containers
 ----------------------------------------
 
-For each input, ``theano.function`` will create a ``Container`` if the
-value was not already a ``Container``. At the time of a function call,
+For each input, ``theano.function`` will create a ``Container`` if
+``value`` was not already a ``Container`` (or if ``implicit`` was ``False``). At the time of a function call,
 each of these containers must be filled with a value. Each input (but
 especially ones with a default value or an update expression) may have a
 value between calls. The function interface defines a way to get at