Ticket #7377: trac_7377-doctests.patch

sage/interfaces/expect.py

@@ -1 +1 @@
 """
-Common Interface Functionality
+Common Interface Functionality through Pexpect
 
 See the examples in the other sections for how to use specific
 interfaces. The interface classes all derive from the generic
@@ -17 +17 @@
 - Simon King (2010-09-25): Expect._local_tmpfile() depends on
   Expect.pid() and is cached; Expect.quit() clears that cache,
   which is important for forking.
+
+- Jean-Pierre Flori (2010,2011): Split non Pexpect stuff into a parent class.
 """
 
 #*****************************************************************************

sage/interfaces/interface.py

@@ -17 +17 @@
 - Simon King (2010-09-25): Expect._local_tmpfile() depends on
   Expect.pid() and is cached; Expect.quit() clears that cache,
   which is important for forking.
+
+- Jean-Pierre Flori (2010,2011): Split non Pexpect stuff into a parent class.
 """
 
 #*****************************************************************************

sage/interfaces/maxima.py

@@ -1 +1 @@
 r"""
-Interface to Maxima
+Pexpect interface to Maxima
 
 Maxima is a free GPL'd general purpose computer algebra system
 whose development started in 1968 at MIT. It contains symbolic
@@ -26 +26 @@
 - William Stein (2006-02-24): *greatly* improved robustness by adding
   sequence numbers to IO bracketing in _eval_line
 
+- Robert Bradshaw, Nils Bruin, Jean-Pierre Flori (2010,2011): Binary library interface
+
+This is the interface used by the maxima object::
+
+    sage: type(maxima)
+    <class 'sage.interfaces.maxima.Maxima'>
+
 If the string "error" (case insensitive) occurs in the output of
 anything from Maxima, a RuntimeError exception is raised.
 
@@ -468 +475 @@
 class Maxima(MaximaAbstract, Expect):
     """
     Interface to the Maxima interpreter.
+
+    EXAMPLES::
+
+        sage: m = Maxima()
+        sage: m == maxima
+        False
     """
     def __init__(self, script_subdirectory=None, logfile=None, server=None,
                  init_code = None):
@@ -567 +580 @@
 
     def __reduce__(self):
         """
+        Implementation of __reduce__ for ``Maxima``.
+
         EXAMPLES::
         
             sage: maxima.__reduce__()
@@ -575 +590 @@
         return reduce_load_Maxima, tuple([])
 
     def _sendline(self, str):
+        """
+        Send a string followed by a newline character.
+
+        EXAMPLES::
+
+            sage: maxima._sendline('t : 9;')
+            sage: maxima.get('t')
+            '9'
+        """
         self._sendstr(str)
         os.write(self._expect.child_fd, os.linesep)
 
@@ -671 +695 @@
     def _eval_line(self, line, allow_use_file=False,
                    wait_for_prompt=True, reformat=True, error_check=True):
         """
+        Return result of line evaluation.
+
         EXAMPLES:
         
         We check that errors are correctly checked::
@@ -794 +820 @@
             self.quit()
 
     def _batch(self, s, batchload=True):
+        """
+        Call Maxima's batch or batchload command with a file containing the given string as argument.
+
+        EXAMPLES::
+
+            sage: maxima._batch('10003;')
+            '...batchload...'
+            sage: maxima._batch('10003;',batchload=False)
+            '...batch...10003...'
+        """
         filename = '%s-%s'%(self._local_tmpfile(),randrange(2147483647))
         F = open(filename, 'w')
         F.write(s)
@@ -815 +851 @@
         self._sendline(cmd)
         self._expect_expr(s)
         out = self._before()
-        self._error_check(str, out)
+        self._error_check(cmd, out)
         os.unlink(filename)
         return out
 
     def _quit_string(self):
         """
+        Return string representation of quit command.
+        
         EXAMPLES::
         
             sage: maxima._quit_string()
@@ -830 +868 @@
 
     def _crash_msg(self):
         """
+        Return string representation of crash message.
+
         EXAMPLES::
         
             sage: maxima._crash_msg()
@@ -837 +877 @@
         """
         print "Maxima crashed -- automatically restarting."
 
-    def _error_check(self, str, out):
+    def _error_check(self, cmd, out):
+        """
+        Check string for errors.
+
+        EXAMPLES::
+        
+            sage: maxima._error_check("1+1;","Principal Value")
+            Traceback (most recent call last):
+            ...
+            TypeError: Error executing code in Maxima
+            CODE:
+                1+1;
+            Maxima ERROR:
+                Principal Value
+        """
         r = self._error_re
         m = r.search(out)
         if not m is None:
-            self._error_msg(str, out)
+            self._error_msg(cmd, out)
             
-    def _error_msg(self, str, out):
-        raise TypeError, "Error executing code in Maxima\nCODE:\n\t%s\nMaxima ERROR:\n\t%s"%(str, out.replace('-- an error.  To debug this try debugmode(true);',''))
+    def _error_msg(self, cmd, out):
+        """
+        Raise error with formated description.
+
+        EXAMPLES::
+
+            sage: maxima._error_msg("1+1;","Principal Value")
+            Traceback (most recent call last):
+            ...
+            TypeError: Error executing code in Maxima
+            CODE:
+                1+1;
+            Maxima ERROR:
+                Principal Value
+        """
+        raise TypeError, "Error executing code in Maxima\nCODE:\n    %s\nMaxima ERROR:\n    %s"%(cmd, out.replace('-- an error.  To debug this try debugmode(true);',''))
 
     ###########################################
     # Direct access to underlying lisp interpreter. 
     ###########################################
     def lisp(self, cmd):
         """
-        Send a lisp command to maxima.
+        Send a lisp command to Maxima.
         
         .. note::
 
@@ -878 +946 @@
         
         INPUT:
         
-        
         -  ``var`` - string
         
         -  ``value`` - string
@@ -935 +1002 @@
 
     def _function_class(self):
         """
+        Return the Python class of Maxima functions.
+
         EXAMPLES::
         
             sage: maxima._function_class()
@@ -954 +1023 @@
         return MaximaElement
 
     def _function_element_class(self):
-        """      
+        """
+        Return the Python class of Maxima functions of elements.
+
         EXAMPLES::
         
             sage: maxima._function_element_class()
@@ -964 +1035 @@
 
     def _object_function_class(self):
         """
+        Return the Python class of Maxima user-defined functions.
+
         EXAMPLES::
         
             sage: maxima._object_function_class()
@@ -971 +1044 @@
         """
         return MaximaElementFunction
 
-    ##some old helper functions to wrap the calculus use of the maxima interface.
+    ##some old helper functions to wrap the calculus use of the Maxima interface.
     ##these routines expect arguments living in the symbolic ring and return something
     ##that is hopefully coercible into the symbolic ring again.
 ##
@@ -1006 +1079 @@
     """
     return isinstance(x, MaximaElement)
 
-# Thanks to the MRO for multiple inheritance used by the Sage's Python , this should work as expected
+# Thanks to the MRO for multiple inheritance used by the Sage's Python, this should work as expected
 class MaximaElement(MaximaAbstractElement, ExpectElement):
+    """
+    Maxima elements.
+
+    EXAMPLES:
+
+    Elements of this class should not be created directly.
+    The targeted parent should be used instead::
+
+        sage: maxima(3)
+        3
+        sage: maxima(cos(x)+e^234)
+        cos(x)+%e^234
+    """
     def __init__(self, parent, value, is_name=False, name=None):
+        """
+        Create a Maxima element.
+        See ``MaximaElement`` for full documentation.
+
+        EXAMPLES::
+
+           sage: maxima(zeta(7))
+           zeta(7)
+        """
         ExpectElement.__init__(self, parent, value, is_name=False, name=None)
 
     def display2d(self, onscreen=True):
         """
+        Return the 2d string representation of this Maxima object.
+
         EXAMPLES::
         
             sage: F = maxima('x^5 - y^5').factor()  
-            sage: F.display2d ()              
+            sage: F.display2d()              
                                    4      3    2  2    3      4
                        - (y - x) (y  + x y  + x  y  + x  y + x )
         """
@@ -1055 +1152 @@
 
 # Thanks to the MRO for multiple inheritance used by the Sage's Python , this should work as expected
 class MaximaElementFunction(MaximaElement, MaximaAbstractElementFunction):
+    """
+    Maxima user-defined functions.
+
+    EXAMPLES:
+
+    Elements of this class should not be created directly.
+    The method ``function`` of the targeted parent should be used instead::
+
+        sage: maxima.function('x,y','h(x)*y')
+        h(x)*y
+    """
+
     def __init__(self, parent, name, defn, args, latex):
+        """
+        Create a Maxima function.
+        See ``MaximaElementFunction`` for full documentation.
+
+        EXAMPLES::
+        
+            sage: maxima.function('x,y','cos(x)+y')
+            cos(x)+y
+        """
         MaximaElement.__init__(self, parent, name, is_name=True)
         MaximaAbstractElementFunction.__init__(self, parent, name, defn, args, latex)
 
@@ -1067 +1185 @@
 
 def reduce_load_Maxima():
     """
+    Unpickle a Maxima Pexpect interface.
+
     EXAMPLES::
     
         sage: from sage.interfaces.maxima import reduce_load_Maxima
@@ -1075 +1195 @@
     """
     return maxima
 
+# This is defined for compatibility with the old Maxima interface.
 def reduce_load_Maxima_function(parent, defn, args, latex):
+    """
+    Unpickle a Maxima function.
+
+    EXAMPLES::
+
+        sage: from sage.interfaces.maxima import reduce_load_Maxima_function
+        sage: f = maxima.function('x,y','sin(x+y)')
+        sage: _,args = f.__reduce__()
+        sage: g = reduce_load_Maxima_function(*args)
+        sage: g == f
+        True
+    """
     return parent.function(args, defn, defn, latex)
 
 def __doctest_cleanup():
+    """
+    Kill all Pexpect interfaces.
+
+    EXAMPLES::
+    
+        sage: from sage.interfaces.maxima import __doctest_cleanup
+        sage: maxima(1)
+        1
+        sage: maxima.is_running()
+        True
+        sage: __doctest_cleanup()
+        sage: maxima.is_running()
+        False
+    """
     import sage.interfaces.quit
     sage.interfaces.quit.expect_quitall()

sage/interfaces/maxima_abstract.py

@@ -1 +1 @@
 r"""
-Interface to Maxima
+Abstract interface to Maxima
 
 Maxima is a free GPL'd general purpose computer algebra system
 whose development started in 1968 at MIT. It contains symbolic
@@ -26 +26 @@
 - William Stein (2006-02-24): *greatly* improved robustness by adding
   sequence numbers to IO bracketing in _eval_line
 
-If the string "error" (case insensitive) occurs in the output of
-anything from Maxima, a RuntimeError exception is raised.
+- Robert Bradshaw, Nils Bruin, Jean-Pierre Flori (2010,2011): Binary library interface
+
+This is an abstract class implementing the functions shared between the Pexpect and library interfaces to Maxima.
 """
 
 #*****************************************************************************
@@ -65 +66 @@
 # documentation from the system -- this could also be useful.
 
 class MaximaAbstract(Interface):
+    r"""
+    Abstract interface to Maxima.
+
+    INPUT:
+
+    - ``name`` - string
+
+    OUTPUT:
+        
+    - the interface
+
+    EXAMPLES:
+        
+    This class should not be instantiated directly,
+    but through its subclasses Maxima (Pexpect interface)
+    or MaximaLib (library interface)::
+
+        sage: m = Maxima()
+        sage: from sage.interfaces.maxima_abstract import MaximaAbstract
+        sage: isinstance(m,MaximaAbstract)
+        True
     """
-    Interface to the Maxima interpreter.
-    """
+
     def __init__(self, name):
-        """
+        r"""
         Create an instance of an abstract interface to Maxima.
+        See ``MaximaAbstract`` for full documentation.
+
+        EXAMPLES::
+
+            sage: from sage.interfaces.maxima_abstract import MaximaAbstract
+            sage: isinstance(maxima,MaximaAbstract)
+            True
         """
         Interface.__init__(self,name)
 
@@ -78 +106 @@
     # System -- change directory, etc
     ###########################################
     def chdir(self, dir):
-        """
+        r"""
         Change Maxima's current working directory.
         
+        INPUT:
+
+        - ``dir`` - string
+
+        OUTPUT: none
+
         EXAMPLES::
         
             sage: maxima.chdir('/')
@@ -91 +125 @@
     # Interactive help
     ###########################################
     def _command_runner(self, command, s, redirect=True):
-        """
+        r"""
         Run ``command`` in a new Maxima session and return its
         output as an ``AsciiArtString``.
+
+        INPUT:
         
-        If redirect is set to False, then the output of the command is not
-        returned as a string. Instead, it behaves like os.system. This is
-        used for interactive things like Maxima's demos. See maxima.demo?
+        - ``command`` - string; function to call
+
+        - ``s`` - string; argument to the function
+
+        - ``redirect`` - boolean (default: True); if redirect is set to False, then the output of the command is not
+          returned as a string. Instead, it behaves like os.system. This is
+          used for interactive things like Maxima's demos. See maxima.demo?
+
+        OUTPUT:
+
+        Output of ``command(s)`` as an ``AsciiArtString`` if ``redirect`` is set to False;
+        None otherwise.
         
         EXAMPLES::
         
@@ -125 +170 @@
             subprocess.Popen(cmd, shell=True)
 
     def help(self, s):
-        """
+        r"""
+        Return Maxima's help for ``s``.
+
+        INPUT:
+
+        - ``s`` - string
+
+        OUTPUT:
+
+        Maxima's help for ``s``
+
         EXAMPLES::
         
             sage: maxima.help('gcd')
             -- Function: gcd (<p_1>, <p_2>, <x_1>, ...)
             ...
         """
+        # Should this be implemented without launching a new Maxima session
+        # i.e. using eval_line ?
         return self._command_runner("describe", s)
 
     def example(self, s):
-        """
+        r"""
+        Return Maxima's examples for ``s``.
+
+        INPUT:
+
+        - ``s`` - string
+
+        OUTPUT:
+
+        Maxima's examples for ``s``
+
         EXAMPLES::
         
             sage: maxima.example('arrays')
@@ -152 +219 @@
                                                   24
                                                  done
         """
+        # Should this be implemented without launching a new Maxima session
+        # i.e. using eval_line ?
         return self._command_runner("example", s)
 
     describe = help
 
     def demo(self, s):
-        """
+        r"""
+        Run Maxima's demo for ``s``.
+
+        INPUT:
+
+        - ``s`` - string
+
+        OUTPUT: none
+
         EXAMPLES::
         
             sage: maxima.demo('array') # not tested
@@ -166 +243 @@
         At the _ prompt, type ';' followed by enter to get next demo
         subscrmap : true _
         """
+        # Should this be implemented without launching a new Maxima session
+        # i.e. using eval_line ?
         return self._command_runner("demo", s, redirect=False)
 
     def completions(self, s, verbose=True):
-        """
+        r"""
         Return all commands that complete the command starting with the
-        string s. This is like typing s[tab] in the Maxima interpreter.
+        string ``s``. This is like typing s[tab] in the Maxima interpreter.
+
+        INPUT:
+
+        - ``s`` - string
+
+        - ``verbose`` - boolean (default: True)
+
+        OUTPUT: array of strings
         
         EXAMPLES::
         
@@ -191 +278 @@
     def _commands(self, verbose=True):
         """
         Return list of all commands defined in Maxima.
+
+        INPUT:
+
+        - ``verbose`` - boolean (default: True)
+
+        OUTPUT: array of strings
         
         EXAMPLES::
         
+            # The output is kind of random
             sage: sorted(maxima._commands(verbose=False))
-            ['Alpha',
-             'Beta',
+            [...
+             'display',
              ...
-             'zunderflow']
+             'gcd',
+             ...
+             'verbose',
+             ...]
         """
         try:
             return self.__commands
@@ -210 +307 @@
         return self.__commands
 
     def trait_names(self, verbose=True, use_disk_cache=True):
-        """
+        r"""
         Return all Maxima commands, which is useful for tab completion.
+
+        INPUT:
+
+        - ``verbose`` - boolean (default: True)
+
+        - ``use_disk_cache`` - boolean (default: True); if set to True, try to read cached result from disk
+
+        OUTPUT: array of strings
         
         EXAMPLES::
         
@@ -247 +352 @@
         Start the interactive Maxima console. This is a completely separate
         maxima session from this interface. To interact with this session,
         you should instead use ``maxima.interact()``.
+
+        INPUT: none
         
+        OUTPUT: none
+
         EXAMPLES::
         
             sage: maxima.console()             # not tested (since we can't)
@@ -273 +382 @@
     def cputime(self, t=None):
         r"""
         Returns the amount of CPU time that this Maxima session has used.
-        If \var{t} is not None, then it returns the difference between
-        the current CPU time and \var{t}.
+
+        INPUT:
+
+        - ``t`` - float (default: None); If \var{t} is not None, then it returns the difference between
+          the current CPU time and \var{t}.
+
+        OUTPUT: float
         
         EXAMPLES:
             sage: t = maxima.cputime()
@@ -288 +402 @@
             return float(self.eval('elapsed_run_time()'))
 
     def version(self):
-        """
+        r"""
         Return the version of Maxima that Sage includes.
+
+        INPUT: none
+        
+        OUTPUT: none
         
         EXAMPLES::
         
@@ -303 +421 @@
     ###
 
     def _assign_symbol(self):
+        r"""
+        Return the assign symbol in Maxima.
+
+        INPUT: none
+        
+        OUTPUT: string
+
+        EXAMPLES::
+
+            sage: maxima._assign_symbol()
+            ':'
+            sage: maxima.eval('t : 8')
+            '8'
+            sage: maxima.eval('t')
+            '8'
+        """
         return ":"
 
     def _true_symbol(self):
         """
         Return the true symbol in Maxima.
+
+        INPUT: none
+        
+        OUTPUT: string
         
         EXAMPLES::
         
@@ -321 +459 @@
     def _false_symbol(self):
         """
         Return the false symbol in Maxima.
+
+        INPUT: none
+        
+        OUTPUT: string
         
         EXAMPLES::
         
@@ -335 +477 @@
         """
         Returns the equality symbol in Maxima.
 
+        INPUT: none
+        
+        OUTPUT: string
+
         EXAMPLES::
 
              sage: maxima._equality_symbol()
              '='
+             sage: var('x y')
+             (x, y)
+             sage: maxima(x == y)
+             x=y
         """
         return '='
 
     def _inequality_symbol(self):
         """
-        Returns the equality symbol in Maxima.
+        Returns the inequality symbol in Maxima.
+
+        INPUT: none
+        
+        OUTPUT: string
 
         EXAMPLES::
 
@@ -357 +511 @@
 
     def _function_class(self):
         """
+        Return the Python class of Maxima functions.
+
+        INPUT: none
+        
+        OUTPUT: type
+
         EXAMPLES::
         
             sage: maxima._function_class()
@@ -367 +527 @@
     def _object_class(self):
         """
         Return the Python class of Maxima elements.
+
+        INPUT: none
+        
+        OUTPUT: type
         
         EXAMPLES::
         
@@ -376 +540 @@
         return MaximaAbstractElement
 
     def _function_element_class(self):
-        """      
+        """
+        Return the Python class of Maxima functions of elements.
+
+        INPUT: none
+        
+        OUTPUT: type
+
         EXAMPLES::
         
             sage: maxima._function_element_class()
@@ -386 +556 @@
 
     def _object_function_class(self):
         """
+        Return the Python class of Maxima user-defined functions.
+
+        INPUT: none
+        
+        OUTPUT: type
+
         EXAMPLES::
         
             sage: maxima._object_function_class()
@@ -393 +569 @@
         """
         return MaximaAbstractElementFunction
 
-    ####
-    #
-    ####
+    ####################
+    # Maxima functions #
+    ####################
 
     def function(self, args, defn, rep=None, latex=None):
         """
@@ -403 +579 @@
         
         INPUT:
         
-        
         -  ``args`` - a string with variable names separated by
            commas
         
@@ -413 +588 @@
         -  ``rep`` - an optional string; if given, this is how
            the function will print.
         
+        OUTPUT: Maxima function
         
         EXAMPLES::
         
@@ -433 +609 @@
             sage: g(1,2,3)
             3*(cos(2)+sin(1))
         
-        The function definition can be a maxima object::
+        The function definition can be a Maxima object::
         
             sage: an_expr = maxima('sin(x)*gamma(x)')
             sage: t = maxima.function('x', an_expr)
@@ -461 +637 @@
             rep = defn
         f = self._object_function_class()(self, name, rep, args, latex)
         return f
-
-    #####
-    # Maxima functions
-    #####
    
 ##     def display2d(self, flag=True):
 ##         """
@@ -496 +668 @@
         
         INPUT:
         
-        
         -  ``f`` - a string representing a function (such as
            f="sin(x)") [var, xmin, xmax]
         
         -  ``options`` - an optional string representing plot2d
            options in gnuplot format
         
-        
         EXAMPLES::
         
             sage: maxima.plot2d('sin(x)','[x,-5,5]')   # not tested
@@ -516 +686 @@
 
     def plot2d_parametric(self, r, var, trange, nticks=50, options=None):
         r"""
-        Plots r = [x(t), y(t)] for t = tmin...tmax using gnuplot with
-        options
+        Plot r = [x(t), y(t)] for t = tmin...tmax using gnuplot with
+        options.
         
         INPUT:
-        
-        
+
         -  ``r`` - a string representing a function (such as
            r="[x(t),y(t)]")
         
@@ -535 +704 @@
         -  ``options`` - an optional string representing plot2d
            options in gnuplot format
         
-        
         EXAMPLES::
         
             sage: maxima.plot2d_parametric(["sin(t)","cos(t)"], "t",[-3.1,3.1])   # not tested
@@ -570 +738 @@
         
         INPUT:
         
-        
         -  ``f`` - a string representing a function (such as
            f="sin(x)") [var, min, max]
         
-        
+        - ``args`` should be of the form '[x, xmin, xmax]', '[y, ymin, ymax]', '[grid, nx, ny]', options
+
         EXAMPLES::
         
             sage: maxima.plot3d('1 + x^3 - y^2', '[x,-2,2]', '[y,-2,2]', '[grid,12,12]')    # not tested
@@ -594 +762 @@
         
         INPUT:
         
-        
         -  ``x, y, z`` - a string representing a function (such
            as ``x="u2+v2"``, ...) vars is a list or two strings
            representing variables (such as vars = ["u","v"])
@@ -607 +774 @@
         -  ``options`` - optional string representing plot2d
            options in gnuplot format
         
-        
         OUTPUT: displays a plot on screen or saves to a file
         
         EXAMPLES::
@@ -649 +815 @@
         
         INPUT:
         
-        
         -  ``de`` - a string representing the ODE
         
         -  ``vars`` - a list of strings representing the two
@@ -658 +823 @@
         -  ``ics`` - a triple of numbers [a,b1,b2] representing
            y(a)=b1, y'(a)=b2
         
-        
         EXAMPLES::
         
             sage: maxima.de_solve('diff(y,x,2) + 3*x = y', ['x','y'], [1,1,1])
@@ -692 +856 @@
         
         INPUT:
         
-        
         -  ``de`` - a string representing the ODE (e.g., de =
            "diff(f(x),x,2)=diff(f(x),x)+sin(x)")
         
@@ -703 +866 @@
            conditions, with symbols allowed which are represented by strings
            (eg, f(0)=1, f'(0)=2 is ics = [0,1,2])
         
-        
         EXAMPLES::
         
             sage: maxima.clear('x'); maxima.clear('f')
@@ -742 +904 @@
         """
         Wraps maxima's linsolve.
         
-        INPUT: eqns is a list of m strings, each representing a linear
-        question in m = n variables vars is a list of n strings, each
+        INPUT: 
+
+        - ``eqns`` - a list of m strings; each representing a linear
+        question in m = n variables
+        - ``vars`` - a list of n strings; each
         representing a variable
         
         EXAMPLES::
@@ -772 +937 @@
         Finds a unit of the ring of integers of the quadratic number field
         `\QQ(\sqrt{n})`, `n>1`, using the qunit maxima
         command.
+
+        INPUT:
+
+        - ``n`` - an integer
         
         EXAMPLES::
         
@@ -804 +973 @@
         
         INPUT:
         
-        
         -  ``ptsx`` - [x1,...,xn], where the xi and yi are
            real,
         
@@ -813 +981 @@
         -  ``options`` - a string representing maxima plot2d
            options.
         
-        
         The points are (x1,y1), (x2,y2), etc.
         
         This function requires maxima 5.9.2 or newer.
@@ -845 +1012 @@
         where each ptsi is of the form [[x1,y1],...,[xn,yn]] x's must be
         integers and y's reals options is a string representing maxima
         plot2d options.
+
+        INPUT:
+        
+        - ``pts_lst`` - list of points; each point must be of the form [x,y]
+          where ``x`` is an integer and ``y`` is a real
+        - ``var`` - string; representing Maxima's plot2d options
         
         Requires maxima 5.9.2 at least.
 
@@ -885 +1058 @@
 class MaximaAbstractElement(InterfaceElement):
     def __str__(self):
         """
-        Printing an object explicitly gives ASCII art:
+        Printing an object explicitly gives ASCII art.
+
+        INPUT: none
+
+        OUTPUT: string
         
         EXAMPLES::
         
@@ -901 +1078 @@
 
     def bool(self):
         """
+        Convert ``self`` into a boolean.
+
+        INPUT: none
+
+        OUTPUT: boolean
+
         EXAMPLES::
         
             sage: maxima(0).bool()
@@ -913 +1096 @@
 
     def __cmp__(self, other):
         """
+        Compare this Maxima object with ``other``.
+
+        INPUT:
+
+        - ``other`` - an object to compare to
+
+        OUTPUT: integer
+
         EXAMPLES::
         
             sage: a = maxima(1); b = maxima(2)
@@ -952 +1143 @@
 
     def _sage_(self):
         """
-        Attempt to make a native Sage object out of this maxima object.
+        Attempt to make a native Sage object out of this Maxima object.
         This is useful for automatic coercions in addition to other
         things.
+
+        INPUT: none
+
+        OUTPUT: Sage object
         
         EXAMPLES::
         
@@ -1000 +1195 @@
 
     def _symbolic_(self, R):
         """
-        Return a symbolic expression equivalent to this maxima object.
+        Return a symbolic expression equivalent to this Maxima object.
+
+        INPUT:
+
+        - ``R`` - symbolic ring to convert into
+
+        OUTPUT: symbolic expression
 
         EXAMPLES::
 
@@ -1010 +1211 @@
             sage: u.parent()
             Symbolic Ring
 
-        This is used when converting maxima objects to the Symbolic Ring::
+        This is used when converting Maxima objects to the Symbolic Ring::
 
             sage: SR(t)
             sqrt(2)
@@ -1019 +1220 @@
 
     def __complex__(self):
         """
+        Return a complex number equivalent to this Maxima object.
+
+        INPUT: none
+
+        OUTPUT: complex
+
         EXAMPLES::
         
             sage: complex(maxima('sqrt(-2)+1'))
@@ -1028 +1235 @@
 
     def _complex_mpfr_field_(self, C):
         """
+        Return a mpfr complex number equivalent to this Maxima object.
+
+        INPUT:
+
+        - ``C`` - complex numbers field to convert into
+
+        OUTPUT: complex
+        
         EXAMPLES::
         
             sage: CC(maxima('1+%i'))
@@ -1047 +1262 @@
 
     def _mpfr_(self, R):
         """
+        Return a mpfr real number equivalent to this Maxima object.
+
+        INPUT:
+
+        - ``R`` - real numbers field to convert into
+
+        OUTPUT: real
+
         EXAMPLES::
         
             sage: RealField(100)(maxima('sqrt(2)+1'))
@@ -1056 +1279 @@
 
     def _complex_double_(self, C):
         """
+        Return a double precision complex number equivalent to this Maxima object.
+
+        INPUT:
+
+        - ``C`` - double precision complex numbers field to convert into
+
+        OUTPUT: complex
+
         EXAMPLES::
         
             sage: CDF(maxima('sqrt(2)+1'))
@@ -1065 +1296 @@
 
     def _real_double_(self, R):
         """
+        Return a double precision real number equivalent to this Maxima object.
+
+        INPUT:
+
+        - ``R`` - double precision real numbers field to convert into
+
+        OUTPUT: real
+
         EXAMPLES::
         
             sage: RDF(maxima('sqrt(2)+1'))
@@ -1074 +1313 @@
 
     def real(self):
         """
-        Return the real part of this maxima element.
+        Return the real part of this Maxima element.
         
+        INPUT: none
+
+        OUTPUT: Maxima real
+
         EXAMPLES::
         
             sage: maxima('2 + (2/3)*%i').real()
@@ -1085 +1328 @@
 
     def imag(self):
         """
-        Return the imaginary part of this maxima element.
+        Return the imaginary part of this Maxima element.
+        
+        INPUT: none
+
+        OUTPUT: Maxima real
         
         EXAMPLES::
         
@@ -1098 +1345 @@
         """
         Return numerical approximation to self as a Maxima object.
         
+        INPUT: none
+
+        OUTPUT: Maxima object
+        
         EXAMPLES::
         
             sage: a = maxima('sqrt(2)').numer(); a
@@ -1109 +1360 @@
 
     def str(self):
         """
-        Return string representation of this maxima object.
+        Return string representation of this Maxima object.
+
+        INPUT: none
+
+        OUTPUT: string
         
         EXAMPLES::
         
@@ -1121 +1376 @@
 
     def __repr__(self):
         """
-        Return print representation of this object.
+        Return print representation of this Maxima object.
+
+        INPUT: none
+
+        OUTPUT: string
+
+        The result is cached.
         
         EXAMPLES::
         
@@ -1143 +1404 @@
         
         INPUT:
         
-        
         -  ``var`` - variable (default: 'x')
         
         -  ``n`` - integer (default: 1)
         
-        
         OUTPUT: n-th derivative of self with respect to the variable var
         
         EXAMPLES::
@@ -1184 +1443 @@
         
         INPUT:
         
-        
         -  ``var`` - variable to integrate with respect to
         
         -  ``a`` - lower endpoint of integration
@@ -1196 +1454 @@
         
         -  ``maximum_num_subintervals`` - (default: 200)
            maxima number of subintervals
-        
-        
+           
         OUTPUT:
         
-        
         -  approximation to the integral
         
         -  estimated absolute error of the
@@ -1224 +1480 @@
 
             -  ``6`` - the input is invalid
         
-        
         EXAMPLES::
         
             sage: maxima('exp(-sqrt(x))').nintegral('x',0,1)
@@ -1251 +1506 @@
         
         INPUT:
         
-        
         -  ``var`` - variable
         
         -  ``min`` - default: None
         
         -  ``max`` - default: None
         
+        OUTPUT:
         
-        Returns the definite integral if xmin is not None, otherwise
-        returns an indefinite integral.
+        - the definite integral if xmin is not None
+        
+        - an indefinite integral otherwise
         
         EXAMPLES::
         
@@ -1296 +1552 @@
 
     def __float__(self):
         """
-        Return floating point version of this maxima element.
+        Return floating point version of this Maxima element.
+
+        INPUT: none
+
+        OUTPUT: real
         
         EXAMPLES::
         
@@ -1315 +1575 @@
     def __len__(self):
         """
         Return the length of a list.
+
+        INPUT: none
+
+        OUTPUT: integer
         
         EXAMPLES::
         
@@ -1328 +1592 @@
     def dot(self, other):
         """
         Implements the notation self . other.
+
+        INPUT:
+
+        - ``other`` - matrix; argument to dot.
+
+        OUTPUT: Maxima matrix
         
         EXAMPLES::
         
@@ -1343 +1613 @@
     def __getitem__(self, n):
         r"""
         Return the n-th element of this list.
+
+        INPUT:
+
+        - ``n`` - integer
+
+        OUTPUT: Maxima object
         
         .. note::
 
@@ -1370 +1646 @@
 
     def __iter__(self):
         """
-        EXAMPLE::
+        Return an iterator for self.
+
+        INPUT: none
+
+        OUTPUT: iterator
+
+        EXAMPLES::
         
             sage: v = maxima('create_list(i*x^i,i,0,5)')
             sage: L = list(v)
@@ -1383 +1665 @@
     def subst(self, val):
         """
         Substitute a value or several values into this Maxima object.
+
+        INPUT:
+
+        - ``val`` - string representing substitution(s) to perform
+
+        OUTPUT: Maxima object
         
         EXAMPLES::
         
@@ -1398 +1686 @@
     def comma(self, args):
         """
         Form the expression that would be written 'self, args' in Maxima.
+
+        INPUT:
+
+        - ``args`` - string
+
+        OUTPUT: Maxima object
         
         EXAMPLES::
         
@@ -1413 +1707 @@
     def _latex_(self):
         """
         Return Latex representation of this Maxima object.
+
+        INPUT: none
+
+        OUTPUT: string
         
         This calls the tex command in Maxima, then does a little
         post-processing to fix bugs in the resulting Maxima output.
@@ -1438 +1736 @@
         P = self.parent()
         s = P._eval_line('tex(%s);'%self.name(), reformat=False)
         if not '$$' in s:
-            raise RuntimeError, "Error texing maxima object."
+            raise RuntimeError, "Error texing Maxima object."
         i = s.find('$$')
         j = s.rfind('$$')
         s = s[i+2:j]
@@ -1462 +1760 @@
     def trait_names(self, verbose=False):
         """
         Return all Maxima commands, which is useful for tab completion.
+
+        INPUT:
+        
+        - ``verbose`` - boolean
+
+        OUTPUT: list of strings
         
         EXAMPLES::
         
@@ -1476 +1780 @@
         If self is a Maxima matrix, return the corresponding Sage matrix
         over the Sage ring `R`.
         
+        INPUT:
+
+        - ``R`` - ring to coerce into
+
+        OUTPUT: matrix
+        
         This may or may not work depending in how complicated the entries
         of self are! It only works if the entries of self can be coerced as
         strings to produce meaningful elements of `R`.
@@ -1517 +1827 @@
         """
         Return the partial fraction decomposition of self with respect to
         the variable var.
+
+        INPUT:
+
+        - ``var`` - string
+
+        OUTPUT: Maxima object
         
         EXAMPLES::
         
@@ -1532 +1848 @@
 
     def _operation(self, operation, right):
         r"""
+        Return the result of "self operation right" in Maxima.
+
+        INPUT:
+
+        - ``operation`` - string; operator
+
+        - ``right`` - Maxima object; right operand
+
+        OUTPUT: Maxima object
+
         Note that right's parent should already be Maxima since this should
         be called after coercion has been performed.
         
@@ -1568 +1894 @@
 
 
 class MaximaAbstractElementFunction(MaximaAbstractElement):
+    r"""
+    Create a Maxima function with the parent ``parent``,
+    name ``name``, definition ``defn``, arguments ``args``
+    and latex representation ``latex``.
+
+    INPUT:
+
+    - ``parent`` - an instance of a concrete Maxima interface
+
+    - ``name`` - string
+
+    - ``defn`` - string
+
+    - ``args`` - string; comma separated names of arguments
+
+    - ``latex`` - string
+
+    OUTPUT: Maxima function
+
+    EXAMPLES::
+        
+        sage: f = maxima.function('x,y','sin(x+y)')
+        sage: f == loads(dumps(f))
+        True
+    """
+
     def __init__(self, parent, name, defn, args, latex):
         """
+        Create a Maxima function.
+        See ``MaximaAbstractElementFunction`` for full documentation.
+
         EXAMPLES::
         
             sage: f = maxima.function('x,y','sin(x+y)')
@@ -1583 +1938 @@
 
     def __reduce__(self):
         """
+        Implement __reduce__ for ``MaximaAbstractElementFunction``.
+
+        INPUT: none
+
+        OUTPUT:
+
+        A couple consisting of:
+
+        - the function to call for unpickling
+        
+        - a tuple of arguments for the function
+
         EXAMPLES::
         
             sage: f = maxima.function('x,y','sin(x+y)')
@@ -1594 +1961 @@
         
     def __call__(self, *x):
         """
+        Return the result of calling this Maxima function with arguments ``*x``.
+
+        INPUT:
+
+        - ``x`` - a variable number of arguments
+
+        OUTPUT: Maxima object
+
         EXAMPLES::
         
             sage: f = maxima.function('x,y','sin(x+y)')
@@ -1609 +1984 @@
 
     def __repr__(self):
         """
+        Return print representation of this Maxima function.
+
+        INPUT: none
+
+        OUTPUT: string
+
         EXAMPLES::
         
             sage: f = maxima.function('x,y','sin(x+y)')
@@ -1619 +2000 @@
 
     def _latex_(self):
         """
+        Return latex representation of this Maxima function.
+
+        INPUT: none
+
+        OUTPUT: string
+
         EXAMPLES::
         
             sage: f = maxima.function('x,y','sin(x+y)')
@@ -1633 +2020 @@
     def arguments(self, split=True):
         r"""
         Returns the arguments of this Maxima function.
+
+        INPUT:
+
+        - ``split`` - boolean; if True return a tuple of strings,
+          otherwise return a string of comma-separated arguments
+
+        OUTPUT:
+
+        - a string if ``split`` is False
+
+        - a list of strings if ``split`` is True
         
         EXAMPLES::
         
@@ -1653 +2051 @@
     def definition(self):
         """
         Returns the definition of this Maxima function as a string.
+
+        INPUT: none
+
+        OUTPUT: string
         
         EXAMPLES::
         
@@ -1665 +2067 @@
     def integral(self, var):
         """
         Returns the integral of self with respect to the variable var.
+
+        INPUT:
+
+        - ``var`` - a variable
+
+        OUTPUT: Maxima function
         
         Note that integrate is an alias of integral.
         
@@ -1692 +2100 @@
         r"""
         This is a utility function which factors out much of the
         commonality used in the arithmetic operations for
-        ``MaximaFunctions``.
+        ``MaximaAbstractElementFunction``.
         
         INPUT:
         
-        
         -  ``operation`` - A string representing the operation
            being performed. For example, '\*', or '1/'.
         
         -  ``f`` - The other operand. If f is
-           ``None``, than the operation is assumed to be unary
+           ``None``, then the operation is assumed to be unary
            rather than binary.
         
-        
         EXAMPLES::
         
             sage: f = maxima.function('x,y','sin(x+y)')
@@ -1733 +2139 @@
 
     def _add_(self, f):
         """
-        MaximaFunction as left summand.
+        This Maxima function as left summand.
         
         EXAMPLES::
         
@@ -1769 +2175 @@
 
     def _sub_(self, f):
         r"""
-        ``MaximaFunction`` as minuend.
+        This Maxima function as minuend.
         
         EXAMPLES::
         
@@ -1794 +2200 @@
         
     def _mul_(self, f):
         r"""
-        ``MaximaFunction`` as left factor.
+        This Maxima function as left factor.
         
         EXAMPLES::
         
@@ -1820 +2226 @@
 
     def _div_(self, f):
         r"""
-        ``MaximaFunction`` as dividend.
+        This Maxima function as dividend.
         
         EXAMPLES::
         
@@ -1846 +2252 @@
 
     def __neg__(self):
         r"""
-        Additive inverse of a ``MaximaFunction``.
+        Additive inverse of this Maxima function.
         
         EXAMPLES::
         
@@ -1858 +2264 @@
 
     def __inv__(self):
         r"""
-        Multiplicative inverse of a ``MaximaFunction``.
+        Multiplicative inverse of this Maxima function.
         
         EXAMPLES::
         
@@ -1870 +2276 @@
 
     def __pow__(self,f):
         r"""
-        ``MaximaFunction`` raised to some power.
+        This Maxima function raised to some power.
         
         EXAMPLES::
         
@@ -1890 +2296 @@
 
 
 def reduce_load_MaximaAbstract_function(parent, defn, args, latex):
+    r"""
+    Unpickle a Maxima function.
+
+    EXAMPLES::
+
+        sage: from sage.interfaces.maxima_abstract import reduce_load_MaximaAbstract_function
+        sage: f = maxima.function('x,y','sin(x+y)')
+        sage: _,args = f.__reduce__()
+        sage: g = reduce_load_MaximaAbstract_function(*args)
+        sage: g == f
+        True
+    """
     return parent.function(args, defn, defn, latex)
     
 def maxima_version():
     """
+    Return Maxima version.
+
+    Currently this calls a new copy of Maxima.
+
     EXAMPLES::
     
         sage: from sage.interfaces.maxima_abstract import maxima_version

sage/interfaces/maxima_lib.py

@@ -1 +1 @@
 r"""
-Interface to Maxima
+Library interface to Maxima
 
 Maxima is a free GPL'd general purpose computer algebra system
 whose development started in 1968 at MIT. It contains symbolic
@@ -26 +26 @@
 - William Stein (2006-02-24): *greatly* improved robustness by adding
   sequence numbers to IO bracketing in _eval_line
 
-If the string "error" (case insensitive) occurs in the output of
-anything from Maxima, a RuntimeError exception is raised.
+- Robert Bradshaw, Nils Bruin, Jean-Pierre Flori (2010,2011): Binary library interface
+
+For this interface, Maxima is loaded into ECL which is itself loaded as a C library in Sage.
+Translations between Sage and Maxima objects (which are nothing but wrappers to ECL objects)
+is made as much as possible directly, but falls back to the string based conversion
+used by the classical Maxima Pexpect interface in case no new implementation has been made.
+
+This interface is the one used for calculus by Sage and is accessible as maxima_calculus::
+
+    sage: maxima_calculus
+    Maxima_lib
+
+Only one instance of this interface can be instantiated,
+so the user should not try to instantiate another one,
+which is anyway set to raise an error::
+
+    sage: from sage.interfaces.maxima_lib import MaximaLib
+    sage: MaximaLib()
+    Traceback (most recent call last):
+    ...
+    RuntimeError: Maxima interface in library mode can only be instantiated once
 """
 
 #*****************************************************************************
@@ -51 +70 @@
 
 from maxima_abstract import MaximaAbstract, MaximaAbstractFunction, MaximaAbstractElement, MaximaAbstractFunctionElement, MaximaAbstractElementFunction
 
-## We begin here by initializing maxima in library mode
+## We begin here by initializing Maxima in library mode
+## i.e. loading it into ECL
 ecl_eval("(setf *load-verbose* NIL)")
 ecl_eval("(require 'maxima)")
 ecl_eval("(in-package :maxima)")
@@ -60 +80 @@
 ecl_eval("(set-locale-subdir)")
 ecl_eval("(set-pathnames)")
 ecl_eval("(defun add-lineinfo (x) x)")
+
 #the following is a direct adaption of the definition of "retrieve" in the Maxima file
 #macsys.lisp. This routine is normally responsible for displaying a question and
 #returning the answer. We change it to throw an error in which the text of the question
@@ -100 +121 @@
 )
 """)
 
+## Redirection of ECL and Maxima stdout to /dev/null
 ecl_eval('(defparameter *dev-null* (make-two-way-stream (make-concatenated-stream) (make-broadcast-stream)))')
-ecl_eval('(defun principal nil (error "Divergent Integral"))')
-ecl_eval("(setf $errormsg nil)")
-
-#ecl_eval(r"(defun tex-derivative (x l r) (tex (if $derivabbrev (tex-dabbrev x) (tex-d x '\partial)) l r lop rop ))")
-
-#ecl_eval('(defun ask-evod (x even-odd)(error "Maxima asks a question"))')
-#ecl_eval('(defun ask-integerp (x)(error "Maxima asks a question"))')
-#ecl_eval('(defun ask-declare (x property)(error "Maxima asks a question"))')
-#ecl_eval('(defun ask-prop (object property fun-or-number)(error "Maxima asks a question"))')
-#ecl_eval('(defun asksign01 (a)(error "Maxima asks a question"))')
-#ecl_eval('(defun asksign (x)(error "Maxima asks a question"))')
-#ecl_eval('(defun asksign1 ($askexp)(error "Maxima asks a question"))')
-#ecl_eval('(defun ask-greateq (x y)(error "Maxima asks a question"))')
-#ecl_eval('(defun askinver (a)(error "Maxima asks a question"))')
-#ecl_eval('(defun npask (exp)(error "Maxima asks a question"))')
-
 ecl_eval("(setf original-standard-output *standard-output*)")
 ecl_eval("(setf *standard-output* *dev-null*)")
 #ecl_eval("(setf *error-output* *dev-null*)")
 
+## Default options set in Maxima
 # display2d -- no ascii art output
 # keepfloat -- don't automatically convert floats to rationals
 init_code = ['display2d : false', 'domain : complex', 'keepfloat : true', 'load(to_poly_solver)', 'load(simplify_sum)']
@@ -137 +144 @@
 ## should allow to do this through a method
 #ecl_eval("(setf *standard-output* original-standard-output)")
 
+## This is the main function (ECL object) used for evalutation
 # This returns an EclObject
 maxima_eval=ecl_eval("""
 (defun maxima-eval( form )
@@ -166 +174 @@
 )
 """)
 
+## Number of instances of this interface
 maxima_lib_instances = 0
 
+## Here we define several useful ECL/Maxima objects
 # The Maxima string function can change the structure of its input
 #maxprint=EclObject("$STRING")
 maxprint=EclObject("(defun mstring-for-sage (form) (coerce (mstring form) 'string))").eval()
@@ -189 +199 @@
 max_to_poly_solve=EclObject("$TO_POLY_SOLVE")
 
 def stdout_to_string(s):
+    r"""
+    Evaluate command ``s`` and catch Maxima stdout (not the result of the command!) into a string.
+
+    INPUT:
+
+    - ``s`` - string; command to evaluate
+
+    OUTPUT: string
+
+    This is currently used to implement display2d.
+
+    EXAMPLES::
+    
+        sage: from sage.interfaces.maxima_lib import stdout_to_string
+        sage: stdout_to_string('1+1')
+        ''
+        sage: stdout_to_string('disp(1+1)')
+        '2\n\n'
+    """
     return ecl_eval("(with-output-to-string (*standard-output*) (maxima-eval #$%s$))"%s).python()[1:-1]
 
 def max_to_string(s):
-     return maxprint(s).python()[1:-1]
+    r"""
+    Return the Maxima string corresponding to this ECL object.
+
+    INPUT:
+
+    - ``s`` - ECL object
+
+    OUTPUT: string
+
+    EXAMPLES::
+
+        sage: from sage.interfaces.maxima_lib import maxima_lib, max_to_string
+        sage: ecl = maxima_lib(cos(x)).ecl()
+        sage: max_to_string(ecl)
+        'cos(x)'
+    """
+    return maxprint(s).python()[1:-1]
 
 my_mread=ecl_eval("""
 (defun my-mread (cmd)
   (caddr (mread (make-string-input-stream cmd))))
 """)
 
-def parse_max_string(l):
-  return my_mread('"%s;"'%l)
+def parse_max_string(s):
+    r"""
+    Evaluate string in Maxima without *any* further simplification.
+
+    INPUT:
+
+    - ``s`` - string
+
+    OUTPUT: ECL object
+
+    EXAMPLES::
+
+        sage: from sage.interfaces.maxima_lib import parse_max_string
+        sage: parse_max_string('1+1')
+        <ECL: ((MPLUS) 1 1)>
+    """
+    return my_mread('"%s;"'%s)
 
 class MaximaLib(MaximaAbstract):
     """
     Interface to Maxima as a Library.
+
+    INPUT: none
+
+    OUTPUT: Maxima interface as a Library
+
+    EXAMPLES::
+
+        sage: from sage.interfaces.maxima_lib import MaximaLib, maxima_lib
+        sage: isinstance(maxima_lib,MaximaLib)
+        True
+
+    Only one such interface can be instantiated::
+
+        sage: MaximaLib()
+        Traceback (most recent call last):
+        ...
+        RuntimeError: Maxima interface in library mode can only be instantiated once
     """
     def __init__(self):
         """
         Create an instance of the Maxima interpreter.
+        See ``MaximaLib`` for full documentation.
 
         TESTS::
 
@@ -229 +307 @@
         global init_code
         self.__init_code = init_code
 
-        ## The name should definitely be changed to maxima_lib, however much more changes are then needed elsewhere
-        ## With maxima, more things are fine, but for example _maxima_init_ gets called in calculus.calculus and the classic interface gets initialized (not started, it is already initialized by default, so that is not really a big deal)
         MaximaAbstract.__init__(self,"maxima_lib")
         self.__seq = 0
  
     def _coerce_from_special_method(self, x):
+        r"""
+        Coerce ``x`` into self trying to call a special underscore method.
+
+        INPUT:
+
+        - ``x`` - object to coerce into self
+
+        OUTPUT: Maxima element equivalent to ``x``
+
+        EXAMPLES::
+
+            sage: from sage.interfaces.maxima_lib import maxima_lib
+            sage: xmax = maxima_lib._coerce_from_special_method(x)
+            sage: type(xmax)
+            <class 'sage.interfaces.maxima_lib.MaximaLibElement'>
+        """
         if isinstance(x, EclObject):
             return MaximaLibElement(self,self._create(x))
         else:
             return MaximaAbstract._coerce_from_special_method(self,x)
         
     def __reduce__(self):
-        """
+        r"""
+        Implement __reduce__ for ``MaximaLib``.
+
+        INPUT: none
+
+        OUTPUT:
+
+        A couple consisting of:
+
+        - the function to call for unpickling
+        
+        - a tuple of arguments for the function
+
         EXAMPLES::
         
             sage: from sage.interfaces.maxima_lib import maxima_lib
@@ -251 +355 @@
         return reduce_load_MaximaLib, tuple([])
 
     # This outputs a string
-    def eval(self, line, locals=None, reformat=True, **kwds):
+    def _eval_line(self, line, locals=None, reformat=True, **kwds):
+        r"""
+        Evaluate the line in Maxima.
+
+        INPUT:
+
+        - ``line`` - string; text to evaluate
+        
+        - ``locals`` - None (ignored); this is used for compatibility with the
+          Sage notebook's generic system interface.
+         
+        - ``reformat`` - boolean; whether to strip output or not
+
+        - ``**kwds`` - All other arguments are currently ignored.
+
+        OUTPUT: string representing Maxima output
+
+        EXAMPLES::
+
+            sage: from sage.interfaces.maxima_lib import maxima_lib
+            sage: maxima_lib._eval_line('1+1')
+            '2'
+            sage: maxima_lib._eval_line('1+1;')
+            '2'
+            sage: maxima_lib._eval_line('1+1$')
+            ''
+            sage: maxima_lib._eval_line('randvar : cos(x)+sin(y)$')
+            ''
+            sage: maxima_lib._eval_line('randvar')
+            'sin(y)+cos(x)'
+        """
         result = ''
         while line:
             ind_dollar=line.find("$")
@@ -272 +406 @@
             return result
         return ''.join([x.strip() for x in result.split()])
 
-    _eval_line = eval
+    eval = _eval_line
 
     ###########################################
     # Direct access to underlying lisp interpreter. 
@@ -281 +415 @@
         """
         Send a lisp command to maxima.
         
+        INPUT:
+
+        - ``cmd`` - string
+
+        OUTPUT: ECL object
+
         .. note::
 
            The output of this command is very raw - not pretty.
@@ -299 +439 @@
         
         INPUT:
         
-        
         -  ``var`` - string
         
         -  ``value`` - string
-        
+
+        OUTPUT: none
         
         EXAMPLES::
         
@@ -321 +461 @@
         """
         Clear the variable named var.
 
+        INPUT:
+
+        - ``var`` - string
+
+        OUTPUT: none
+
         EXAMPLES::
 
             sage: from sage.interfaces.maxima_lib import maxima_lib
@@ -339 +485 @@
     def get(self, var):
         """
         Get the string value of the variable var.
+
+        INPUT:
+
+        - ``var`` - string
+
+        OUTPUT: string
         
         EXAMPLES::
         
@@ -351 +503 @@
         return s
  
     def _create(self, value, name=None):
+        r"""
+        Create a variable with given value and name.
+
+        INPUT:
+
+        - ``value`` - string or ECL object
+
+        - ``name`` - string (default: None); name to use for the variable,
+          an automatically generated name is used if this is none
+
+        OUTPUT:
+
+        - string; the name of the created variable
+
+        EXAMPLES:
+
+        Creation from strings::
+
+            sage: from sage.interfaces.maxima_lib import maxima_lib
+            sage: maxima_lib._create('3','var3')
+            'var3'
+            sage: maxima_lib.get('var3')
+            '3'
+            sage: s = maxima_lib._create('3')
+            sage: s # random output
+            'sage9'
+            sage: s[:4] == 'sage'
+            True
+
+        And from ECL object::
+
+            sage: c = maxima_lib(x+cos(19)).ecl()
+            sage: maxima_lib._create(c,'m')
+            'm'
+            sage: maxima_lib.get('m')
+            'x+cos(19)'
+        """
         name = self._next_var_name() if name is None else name
         if isinstance(value,EclObject):
             maxima_eval([[msetq],cadadr("#$%s$#$"%name),value])
@@ -359 +548 @@
         return name
 
     def _function_class(self):
-        """
+        r"""
+        Return the Python class of Maxima functions.
+
+        INPUT: none
+        
+        OUTPUT: type
+
         EXAMPLES::
         
             sage: from sage.interfaces.maxima_lib import maxima_lib
@@ -369 +564 @@
         return MaximaLibFunction
 
     def _object_class(self):
-        """
+        r"""
         Return the Python class of Maxima elements.
+
+        INPUT: none
+        
+        OUTPUT: type
         
         EXAMPLES::
         
@@ -381 +580 @@
         return MaximaLibElement
 
     def _function_element_class(self):
-        """      
+        r"""
+        Return the Python class of Maxima functions of elements.
+
+        INPUT: none
+        
+        OUTPUT: type
+
         EXAMPLES::
         
             sage: from sage.interfaces.maxima_lib import maxima_lib
@@ -391 +596 @@
         return MaximaLibFunctionElement
 
     def _object_function_class(self):
-        """
+        r"""
+        Return the Python class of Maxima user-defined functions.
+
+        INPUT: none
+        
+        OUTPUT: type
+
         EXAMPLES::
         
             sage: from sage.interfaces.maxima_lib import maxima_lib
@@ -562 +773 @@
 
 
 def is_MaximaLibElement(x):
-    """
+    r"""
     Returns True if x is of type MaximaLibElement.
     
     EXAMPLES::
@@ -576 +787 @@
     """
     return isinstance(x, MaximaLibElement)
 
-class MaximaLibElement(MaximaAbstractElement):
-    """
-    """    
+class MaximaLibElement(MaximaAbstractElement):   
     def ecl(self):
+        r"""
+        Return the underlying ECL object of this MaximaLib object.
+
+        INPUT: none
+
+        OUTPUT: ECL object
+
+        EXAMPLES::
+
+            sage: from sage.interfaces.maxima_lib import maxima_lib
+            sage: maxima_lib(x+cos(19)).ecl()
+            <ECL: ((MPLUS SIMP) ((%COS SIMP) 19) $X)>
+        """
         try:
             return self._ecl
         except AttributeError:
@@ -587 +809 @@
             return self._ecl
             
     def to_poly_solve(self,vars,options=""):
+        r"""
+        Use Maxima's to_poly_solver package.
+
+        INPUT:
+
+        - ``vars`` - symbolic expressions
+
+        - ``options`` - string (default="")
+
+        OUTPUT: Maxima object
+
+        EXAMPLES::
+
+            sage: from sage.interfaces.maxima_lib import maxima_lib
+            sage: sol = maxima_lib(sin(x) == 0).to_poly_solve(x)
+            sage: sol.sage()
+            [[x == pi + 2*pi*z6], [x == 2*pi*z8]]
+        """
         if options.find("use_grobner=true") != -1:
             cmd=EclObject([[max_to_poly_solve], self.ecl(), sr_to_max(vars),
                                              [[mequal],max_use_grobner,True]])
@@ -595 +835 @@
         return self.parent()(maxima_eval(cmd))
 
     def display2d(self, onscreen=True):
-        """
+        r"""
+        Return the 2d representation of this Maxima object.
+
+        INPUT:
+
+        - ``onscreen`` - boolean (default: True); whether to print or return
+
+        OUTPUT:
+
+        The representation is printed if onscreen is set to True
+        and returned as a string otherwise.
+
         EXAMPLES::
         
             sage: from sage.interfaces.maxima_lib import maxima_lib
             sage: F = maxima_lib('x^5 - y^5').factor()  
-            sage: F.display2d ()              
+            sage: F.display2d()              
                                    4      3    2  2    3      4
                        - (y - x) (y  + x y  + x  y  + x  y + x )
         """
@@ -638 +889 @@
 
 
 def reduce_load_MaximaLib():
-    """
+    r"""
+    Unpickle the Maxima library interface.
+
     EXAMPLES::
     
         sage: from sage.interfaces.maxima_lib import reduce_load_MaximaLib
@@ -647 +900 @@
     """
     return maxima_lib
 
-#**********************************
-# ???
 
+#############################################
+# Smart translations between SR and Maxima
+#############################################
+
+import sage.rings.real_double
 import sage.symbolic.expression
 import sage.functions.trig
 import sage.functions.log
@@ -667 +923 @@
 cadadr=EclObject("cadadr")
 meval=EclObject("meval")
 NIL=EclObject("NIL")
-ratdisrep=EclObject("ratdisrep")
 
+## Dictionaries for standard operators
 sage_op_dict = {
     sage.symbolic.expression.operator.abs : "MABS",
     sage.symbolic.expression.operator.add : "MPLUS",
@@ -707 +963 @@
 sage_op_dict = dict([(k,EclObject(sage_op_dict[k])) for k in sage_op_dict])
 max_op_dict = dict([(sage_op_dict[k],k) for k in sage_op_dict])
 
+
+## Here we correct the dictionaries for some simple operators
 def add_vararg(*args):
+    r"""
+    Addition of a variable number of arguments.
+
+    INPUT:
+    
+    - ``args`` - arguments to add
+
+    OUTPUT: sum of arguments
+
+    EXAMPLES::
+
+        sage: from sage.interfaces.maxima_lib import add_vararg
+        sage: add_vararg(1,2,3,4,5,6,7)
+        28
+    """
     S=0
     for a in args:
         S=S+a
     return S
 
 def mul_vararg(*args):
+    r"""
+    Multiplication of a variable number of arguments.
+
+    INPUT:
+    
+    - ``args`` - arguments to multiply
+
+    OUTPUT: product of arguments
+
+    EXAMPLES::
+
+        sage: from sage.interfaces.maxima_lib import mul_vararg
+        sage: mul_vararg(9,8,7,6,5,4)
+        60480
+    """
     P=1
     for a in args:
         P=P*a
     return P
 
 def sage_rat(x,y):
+    r"""
+    Return quotient x/y.
+
+    INPUT:
+
+    - ``x`` - integer
+
+    - ``y`` - integer
+
+    OUTPUT: rational
+
+    EXAMPLES::
+
+        sage: from sage.interfaces.maxima_lib import sage_rat
+        sage: sage_rat(1,7)
+        1/7
+    """
     return x/y
 
 mplus=EclObject("MPLUS")
 mtimes=EclObject("MTIMES")
-mdiff=EclObject("%DERIVATIVE")
 rat=EclObject("RAT")
-max_i=EclObject("$%I")
 max_op_dict[mplus]=add_vararg
 max_op_dict[mtimes]=mul_vararg
 max_op_dict[rat]=sage_rat
+
+
+## Here we build dictionaries for operators needing special conversions.
+ratdisrep=EclObject("ratdisrep")
+mrat=EclObject("MRAT")
 mqapply=EclObject("MQAPPLY")
 max_li=EclObject("$LI")
 max_psi=EclObject("$PSI")
 max_array=EclObject("ARRAY")
+mdiff=EclObject("%DERIVATIVE")
 max_gamma_incomplete=sage_op_dict[sage.functions.other.gamma_inc]
 
 def mrat_to_sage(expr):
     r"""
-    Convert a maxima MRAT expression to Sage SR
+    Convert a Maxima MRAT expression to Sage SR.
     
+    INPUT:
+
+    - ``expr`` - ECL object; a Maxima MRAT expression
+
+    OUTPUT: symbolic expression
+
     Maxima has an optimised representation for multivariate rational expressions.
-    The easiest way to translate those to SR is by first asking maxima to give
+    The easiest way to translate those to SR is by first asking Maxima to give
     the generic representation of the object. That is what RATDISREP does in
-    maxima.
+    Maxima.
+
+    EXAMPLES::
+
+        sage: from sage.interfaces.maxima_lib import maxima_lib, mrat_to_sage
+        sage: var('x y z')
+        (x, y, z)
+        sage: c = maxima_lib((x+y^2+z^9)/x^6+z^8/y).rat()
+        sage: c
+        (y*z^9+x^6*z^8+y^3+x*y)/(x^6*y)
+        sage: c.ecl()
+        <ECL: ((MRAT SIMP ($X $Y $Z)
+        ...>
+        sage: mrat_to_sage(c.ecl())
+        (x^6*z^8 + y*z^9 + y^3 + x*y)/(x^6*y)
     """
     return max_to_sr(meval(EclObject([[ratdisrep],expr])))
 
 def mqapply_to_sage(expr):
     r"""
-    Special conversion rule for MQAPPLY expressions
+    Special conversion rule for MQAPPLY expressions.
+
+    INPUT:
+
+    - ``expr`` - ECL object; a Maxima MQAPPLY expression
+
+    OUTPUT: symbolic expression
+
+    MQAPPLY is used for function as li[x](y) and psi[x](y).
+
+    EXAMPLES::
+
+        sage: from sage.interfaces.maxima_lib import maxima_lib, mqapply_to_sage
+        sage: c = maxima_lib('li[2](3)')
+        sage: c.ecl()
+        <ECL: ((MQAPPLY SIMP) (($LI SIMP ARRAY) 2) 3)>
+        sage: mqapply_to_sage(c.ecl())
+        polylog(2, 3)
     """
     if caaadr(expr) == max_li:
         return sage.functions.log.polylog(max_to_sr(cadadr(expr)),max_to_sr(caddr(expr)))
@@ -761 +1107 @@
         args=[max_to_sr(a) for a in max_args]
         return op(*args)
 
+def mdiff_to_sage(expr):
+    r"""
+    Special conversion rule for %DERIVATIVE expressions.
+
+    INPUT:
+
+    - ``expr`` - ECL object; a Maxima %DERIVATIVE expression
+
+    OUTPUT: symbolic expression
+
+    EXAMPLES::
+
+        sage: from sage.interfaces.maxima_lib import maxima_lib, mdiff_to_sage
+        sage: f = maxima_lib('f(x)').diff('x',4)
+        sage: f.ecl()
+        <ECL: ((%DERIVATIVE SIMP) (($F SIMP) $X) $X 4)>
+        sage: mdiff_to_sage(f.ecl())
+        D[0, 0, 0, 0](f)(x)
+    """
+    return max_to_sr(expr.cadr()).diff(*[max_to_sr(e) for e in expr.cddr()])
+
 def dummy_integrate(expr):
     r"""
-    we would like to simply tie maxima's integrate to sage.calculus.calculus.dummy_integrate, but we're being imported there so to avoid circularity we define it here.
+    We would like to simply tie Maxima's integrate to sage.calculus.calculus.dummy_integrate, but we're being imported there so to avoid circularity we define it here.
+
+    INPUT:
+
+    - ``expr`` - ECL object; a Maxima %INTEGRATE expression
+
+    OUTPUT: symbolic expression
+
+    EXAMPLES::
+        sage: from sage.interfaces.maxima_lib import maxima_lib, dummy_integrate
+        sage: f = maxima_lib('f(x)').integrate('x')
+        sage: f.ecl()
+        <ECL: ((%INTEGRATE SIMP) (($F SIMP) $X) $X)>
+        sage: dummy_integrate(f.ecl())
+        integrate(f(x), x)
+
+    ::
+        sage: f = maxima_lib('f(x)').integrate('x',0,10)
+        sage: f.ecl()
+        <ECL: ((%INTEGRATE SIMP) (($F SIMP) $X) $X 0 10)>
+        sage: dummy_integrate(f.ecl())
+        integrate(f(x), x, 0, 10)
     """
     args=[max_to_sr(a) for a in cdr(expr)]
     if len(args) == 4 :
@@ -771 +1159 @@
     else:
         return sage.symbolic.integration.integral.indefinite_integral(*args, hold=True)
 
-def mdiff_to_sage(expr):
-    return max_to_sr(expr.cadr()).diff(*[max_to_sr(e) for e in expr.cddr()])
-
+## The dictionaries
 special_max_to_sage={
-    EclObject("MRAT") : mrat_to_sage,
+    mrat : mrat_to_sage,
     mqapply : mqapply_to_sage,
-    EclObject("%INTEGRATE") : dummy_integrate,
-    mdiff : mdiff_to_sage
+    mdiff : mdiff_to_sage,
+    EclObject("%INTEGRATE") : dummy_integrate
 }
 
 special_sage_to_max={
@@ -788 +1174 @@
     sage.functions.other.Ei : lambda X : [[max_gamma_incomplete], 0, X]
 }
 
+
+## Dictionaries for symbols
 sage_sym_dict={}
 max_sym_dict={}
 
+
+## Generic conversion functions
+
+max_i=EclObject("$%I")
 def pyobject_to_max(obj):
+    r"""
+    Convert a (simple) Python object into a Maxima object.
+
+    INPUT:
+
+    - ``expr`` - Python object
+
+    OUTPUT: ECL object
+
+    .. note::
+    This uses functions defined in sage.libs.ecl.
+
+    EXAMPLES::
+        sage: from sage.interfaces.maxima_lib import pyobject_to_max
+        sage: pyobject_to_max(4)
+        <ECL: 4>
+        sage: pyobject_to_max('z')
+        <ECL: Z>
+        sage: var('x')
+        x
+        sage: pyobject_to_max(x)
+        Traceback (most recent call last):
+        ...
+        TypeError: Unimplemented type for python_to_ecl
+    """
     if isinstance(obj,sage.rings.rational.Rational):
         return EclObject(obj) if (obj.denom().is_one()) else EclObject([[rat], obj.numer(),obj.denom()])
     elif isinstance(obj,sage.rings.number_field.number_field_element_quadratic.NumberFieldElement_quadratic) and obj.parent().defining_polynomial().list() == [1,0,1]:
@@ -802 +1219 @@
 # This goes from SR to EclObject
 def sr_to_max(expr):
     r"""
+    Convert a symbolic expression into a Maxima object.
+
+    INPUT:
+
+    - ``expr`` - symbolic expression
+
+    OUTPUT: ECL object
+
+    EXAMPLES::
+        sage: from sage.interfaces.maxima_lib import sr_to_max
+        sage: var('x')
+        x
+        sage: sr_to_max(x)
+        <ECL: $X>
+        sage: sr_to_max(cos(x))
+        <ECL: ((%COS) $X)>
+        sage: f = function('f',x)
+        sage: sr_to_max(f.diff())
+        <ECL: ((%DERIVATIVE) (($F) $X) $X 1)>
     """
     global sage_op_dict, max_op_dict
     global sage_sym_dict, max_sym_dict
@@ -822 +1258 @@
             params = op.parameter_set()
             deriv_max = []
             [deriv_max.extend([sr_to_max(args[i]), EclObject(params.count(i))]) for i in set(params)]
-            l = [mdiff,f]
+            l = [[mdiff],f]
             l.extend(deriv_max)
             return EclObject(l)
         elif (op in special_sage_to_max):
@@ -850 +1286 @@
             return maxima(expr).ecl()
     
 # This goes from EclObject to SR
-import sage.rings.real_double
+def max_to_sr(expr):
+    r"""
+    Convert a Maxima object into a symbolic expression.
 
-def max_to_sr(expr):
+    INPUT:
+
+    - ``expr`` - ECL object
+
+    OUTPUT: symbolic expression
+
+    EXAMPLES::
+
+        sage: from sage.interfaces.maxima_lib import maxima_lib, max_to_sr
+        sage: f = maxima_lib('f(x)')
+        sage: f.ecl()
+        <ECL: (($F SIMP) $X)>
+        sage: max_to_sr(f.ecl())
+        f(x)
+
+    TESTS::
+
+        sage: from sage.interfaces.maxima_lib import sr_to_max, max_to_sr
+        sage: f = function('f',x).diff()
+        sage: bool(max_to_sr(sr_to_max(f)) == f)
+        True
+    """
     if expr.consp():
         op_max=caar(expr)
         if op_max in special_max_to_sage:
             return special_max_to_sage[op_max](expr)
         if not(op_max in max_op_dict):
-            # This could be unsafe if the conversion to SR chenges the structure of expr
+            # This could be unsafe if the conversion to SR changes the structure of expr
             sage_expr=SR(maxima(expr))
             max_op_dict[op_max]=sage_expr.operator()
             sage_op_dict[sage_expr.operator()]=op_max