Improve docs and comments of some internal tools, and of testing code

IPython/core/displayhook.py

@@ -260,11 +260,14 b' class DisplayHook(Configurable):'
                 self.flush()
             # Don't overwrite '_' and friends if '_' is in __builtin__ (otherwise
             # we cause buggy behavior for things like gettext).
+
             if '_' not in __builtin__.__dict__:
                 self.___ = self.__
                 self.__ = self._
                 self._ = result
-                self.shell.user_ns.update({'_':self._,'__':self.__,'___':self.___})
+                self.shell.user_ns.update({'_':self._,
+                                           '__':self.__,
+                                           '___':self.___})
 
             # hackish access to top-level  namespace to create _1,_2... dynamically
             to_main = {}

IPython/core/interactiveshell.py

@@ -4,7 +4,7 b''
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2001 Janko Hauser <[e-mail]>
 #  Copyright (C) 2001-2007 Fernando Perez. <[e-mail]>
-#  Copyright (C) 2008-2010  The IPython Development Team
+#  Copyright (C) 2008-2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
@@ -2154,15 +2154,28 b' class InteractiveShell(Configurable, Magic):'
         self.execution_count += 1
 
     def run_one_block(self, block):
-        """Run a single interactive block.
+        """Run a single interactive block of source code.
 
         If the block is single-line, dynamic transformations are applied to it
         (like automagics, autocall and alias recognition).
+
+        If the block is multi-line, it must consist of valid Python code only.
+
+        Parameters
+        ----------
+        block : string
+           A (possibly multiline) string of code to be executed.
+
+        Returns
+        -------
+        The output of the underlying execution method used, be it
+        :meth:`run_source` or :meth:`run_single_line`.
         """
         if len(block.splitlines()) <= 1:
             out = self.run_single_line(block)
         else:
             out = self.run_code(block)
+            #out = self.run_source(block)
         return out
 
     def run_single_line(self, line):
@@ -2316,7 +2329,7 b' class InteractiveShell(Configurable, Magic):'
         try:
             try:
                 self.hooks.pre_run_code_hook()
-                #rprint('Running code') # dbg
+                #rprint('Running code', repr(code_obj)) # dbg
                 exec code_obj in self.user_global_ns, self.user_ns
             finally:
                 # Reset our crash handler in place

IPython/core/tests/test_inputsplitter.py

@@ -1,5 +1,10 b''
 # -*- coding: utf-8 -*-
 """Tests for the inputsplitter module.
+
+Authors
+-------
+* Fernando Perez
+* Robert Kern
 """
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2010  The IPython Development Team

IPython/testing/globalipapp.py

@@ -86,9 +86,11 b' class ipnsdict(dict):'
         self._checkpoint()
         dict.update(self,other)
 
-        # If '_' is in the namespace, python won't set it when executing code,
-        # and we have examples that test it.  So we ensure that the namespace
-        # is always 'clean' of it before it's used for test code execution.
+        # If '_' is in the namespace, python won't set it when executing code
+        # *in doctests*, and we have multiple doctests that use '_'.  So we
+        # ensure that the namespace is always 'clean' of it before it's used
+        # for test code execution.  Note: this means that outside of doctests,
+        # our own testing 
         self.pop('_',None)
 
         # The builtins namespace must *always* be the real __builtin__ module,