longer stories about DebugMode exceptions

doc/advanced/debugmode.txt

@@ -43,42 +43,87 @@ In the example above, there is no way to guarantee that a future call to say,
 BadCLinkerOutput
 ----------------
 
-This really just means that python and c didn't match.  The problem might be a
-bug in either python or c or both.
+This exception means that python (``perform``) and c (``c_code``) for an Op
+didn't compute the same thing like they were supposed to.
+The problem might be a bug in either ``perform`` or ``c_code`` (or both).
+
+For detailed documentation see :api:`BadCLinkerOutput`.
+
 
 BadOptimization
 ---------------
 
-This happens when ... WRITEME.
+This exception indicates that an Optimization replaced one variable (say V1)
+with another one (say V2)  but at runtime, the values for V1 and V2 were
+different.  This is something that optimizations are not supposed to do.
+
+It can be tricky to identify the one-true-cause of an optimization error, but
+this exception provides a lot of guidance.  Most of the time, the
+exception object will indicate which optimization was at fault.
+The exception object also contains information such as a snapshot of the
+before/after graph where the optimization introduced the error.
+
+For detailed documentation see :api:`BadOptimization`.
+
 
 BadDestroyMap
 -------------
 
 This happens when an Op's perform() or c_code() modifies an input that it wasn't
-supposed to.
-For detailed documentation see :api:`BadDestroyMap`.
+supposed to.  If either the ``perform`` or ``c_code`` implementation of an Op
+might modify any input, it has to advertise that fact via the ``destroy_map``
+attribute.
+
+For detailed documentation on the Exception see :api:`BadDestroyMap`.
+
+For detailed documentation on the ``destroy_map`` attribute :ref:`destroymap`.
 
 
 BadViewMap
 ----------
-This happens when ... WRITEME.
+
+This happens when an Op's perform() or c_code() creates an alias or alias-like
+dependency between an input and an output... and it didn't warn the
+optimization system via the ``view_map`` attribute.
+
+For detailed documentation on the Exception see :api:`BadViewMap`.
+
+For detailed documentation on the ``view_map`` attribute :ref:`destroymap`.
 
 
 StochasticOrder
 ---------------
 
-This happens when ... WRITEME.
+This happens when an optimization does not perform the same graph operations
+in the same order when run several times in a row.  This can happen if any
+steps are ordered by ``id(object)`` somehow, such as via the default object
+hash function.  A Stochastic optimization invalidates the pattern of work
+whereby we debug in DEBUG_MODE and then run the full-size jobs in FAST_RUN.
+
+For detailed documentation see :api:`StochasticOrder`.
+
 
 FloatError
 ----------
 
-This happens when ... WRITEME.
+This happens when invalid floating-point values such as NaN and Inf are
+introduced into the computations.  It indicates which Op created the first
+NaN.
+
+Currently this exception is never raised because the check is not being
+performed, but the plan is that it will be.  (see ticket #320)
+
+For detailed documentation see :api:`FloatError`.
 
 InvalidValueError
 -----------------
 
-This happens when ... WRITEME.
+This happens when some Op's ``perform`` or ``c_code`` implementation computes
+an output that is invalid with respect to the type of the corresponding output
+variable.  Like if it returned a complex-valued ndarray for a ``dscalar``
+Type.
 
+For detailed documentation see :api:`InvalidValueError`.
 
 DebugModeError
 --------------
@@ -86,3 +131,5 @@ DebugModeError
 This is a generic error, pretty unhelpful.  You'll generally have to look at the
 stack trace and then in the code to figure out why DebugMode is complaining.
 
+For detailed documentation see :api:`DebugModeError`.
+