More updates to comments and docstrings.

IPython/nbconvert/utils/lexers.py

@@ -217,10 +217,8 b' class IPythonConsoleLexer(Lexer):'
     aliases = ['ipythoncon']
     mimetypes = ['text/x-ipython-console']
 
-    # The regexps used to determine what is input and what is output. The
-    # input regex should be consistent with and also be the combination of
-    # the values of the `in_template` and `in2_templates`. For example, the
-    # defaults prompts are:
+    # The regexps used to determine what is input and what is output.
+    # The default prompts for IPython are:
     #
     #     c.PromptManager.in_template  = 'In [\#]: '
     #     c.PromptManager.in2_template = '   .\D.: '
@@ -322,11 +320,24 b' class IPythonConsoleLexer(Lexer):'
         self.buffer = u''
         self.insertions = []
 
-    def get_modecode(self, line):
+    def get_mci(self, line):
         """
-        Returns the next mode and code to be added to the next mode's buffer.
+        Parses the line and returns a 3-tuple: (mode, code, insertion).
 
-        The next mode depends on current mode and contents of line.
+        `mode` is the next mode (or state) of the lexer, and is always equal
+        to 'input', 'output', or 'tb'.
+
+        `code` is a portion of the line that should be added to the buffer
+        corresponding to the next mode and eventually lexed by another lexer.
+        For example, `code` could be Python code if `mode` were 'input'.
+
+        `insertion` is a 3-tuple (index, token, text) representing an
+        unprocessed "token" that will be inserted into the stream of tokens
+        that are created from the buffer once we change modes. This is usually
+        the input or output prompt.
+
+        In general, the next mode depends on current mode and on the contents
+        of `line`.
 
         """
         # To reduce the number of regex match checks, we have multiple
@@ -436,7 +447,7 b' class IPythonConsoleLexer(Lexer):'
         self.reset()
         for match in line_re.finditer(text):
             line = match.group()
-            mode, code, insertion = self.get_modecode(line)
+            mode, code, insertion = self.get_mci(line)
 
             if mode != self.mode:
                 # Yield buffered tokens before transitioning to new mode.

docs/source/whatsnew/pr/ipython-console-lexer.rst

@@ -27,32 +27,36 b' available at :module:`IPython.nbconvert.utils.lexers`. These include:'
 Previously, the :class:`IPythonConsoleLexer` class was available at
 :module:`IPython.sphinxext.ipython_console_hightlight`.  It was inserted
 into Pygments' list of available lexers under the name `ipython`.  It should
-be mentioned that this name is inaccurate.  An IPython console session
+be mentioned that this name is inaccurate, since an IPython console session
 is not the same as IPython code (which itself is a superset of the Python
 language).
 
-Now, the Sphinx extension inserts two console lexers into Pygment's list of
-available lexers.  Both are IPyLexer instances under the names:  `ipython` and
-`ipython3`. As mentioned above, these names are misleading, but they are kept
-for backwards compatibility and typical usage.  If a project needs to make
-Pygments aware of more than just the IPyLexer class, then one should not
-make the IPyLexer class available under the name `ipython` and use `ipy` or
-some other non-conflicting value.
+Now, the Sphinx extension inserts two console lexers into Pygments' list of
+available lexers. Both are IPyLexer instances under the names: `ipython` and
+`ipython3`. Although the names can be confusing (as mentioned above), their
+continued use is, in part, to maintain backwards compatibility and to
+aid typical usage. If a project needs to make Pygments aware of more than just
+the IPyLexer class, then one should not make the IPyLexer class available under
+the name `ipython` and use `ipy` or some other non-conflicting value.
 
-Code blocks such as::
+Code blocks such as:
+
+.. code-block:: rst
 
     .. code-block:: ipython
 
-       In [1]: 2**2
-       Out[1]: 4
+        In [1]: 2**2
+    Out[1]: 4
 
 will continue to work as before, but now, they will also properly highlight
-tracebacks.  For pure IPython code, the same lexer will work::
+tracebacks.  For pure IPython code, the same lexer will also work:
+
+.. code-block:: rst
 
     .. code-block:: ipython
 
-       x = ''.join(map(str, range(10)))
-       !echo $x
+        x = ''.join(map(str, range(10)))
+    !echo $x
 
 Since the first line of the block did not begin with a standard IPython console
-prompt, the entire block is assumed to be IPython code instead.
+prompt, the entire block is assumed to consist of IPython code instead.