From d42a12c7665bce35a1b52f0f6f0b14108252ba60 2011-02-04 01:51:16
From: Fernando Perez <Fernando.Perez@berkeley.edu>
Date: 2011-02-04 01:51:16
Subject: [PATCH] Improve docs and comments of some internal tools, and of testing code

---

diff --git a/IPython/core/displayhook.py b/IPython/core/displayhook.py
index c5d3116..409ff14 100644
--- a/IPython/core/displayhook.py
+++ b/IPython/core/displayhook.py
@@ -260,11 +260,14 @@ 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 = {}
diff --git a/IPython/core/interactiveshell.py b/IPython/core/interactiveshell.py
index 0fa9a2f..5846cd2 100644
--- a/IPython/core/interactiveshell.py
+++ b/IPython/core/interactiveshell.py
@@ -4,7 +4,7 @@
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
 #  Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
-#  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 @@ 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 @@ 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
diff --git a/IPython/core/tests/test_inputsplitter.py b/IPython/core/tests/test_inputsplitter.py
index 9ebc831..5b2cb9c 100644
--- a/IPython/core/tests/test_inputsplitter.py
+++ b/IPython/core/tests/test_inputsplitter.py
@@ -1,5 +1,10 @@
 # -*- coding: utf-8 -*-
 """Tests for the inputsplitter module.
+
+Authors
+-------
+* Fernando Perez
+* Robert Kern
 """
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2010  The IPython Development Team
diff --git a/IPython/testing/globalipapp.py b/IPython/testing/globalipapp.py
index 7c0f202..d684ce3 100644
--- a/IPython/testing/globalipapp.py
+++ b/IPython/testing/globalipapp.py
@@ -86,9 +86,11 @@ 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,