Merge pull request #5008 from ivanov/messaging-doc

updated explanation of 'pyin' messages

docs/source/development/messaging.rst

@@ -402,6 +402,8 b' the outcome. See :ref:`below <execution_results>` for the possible return'
 codes and associated data.
 
 
+.. _execution_counter:
+
 Execution counter (old prompt number)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -410,7 +412,7 b' requests that are made with ``store_history=True``. This counter is used to pop'
 the ``In[n]``, ``Out[n]`` and ``_n`` variables, so clients will likely want to
 display it in some form to the user, which will typically (but not necessarily)
 be done in the prompts.  The value of this counter will be returned as the
-``execution_count`` field of all ``execute_reply`` messages.
+``execution_count`` field of all ``execute_reply`` and ``pyin`` messages.
 
 .. _execution_results:
 
@@ -832,12 +834,6 b' frontend to decide which to use and how. A single message should contain all'
 possible representations of the same information. Each representation should
 be a JSON'able data structure, and should be a valid MIME type.
 
-Some questions remain about this design:
-
-* Do we use this message type for pyout/displayhook? Probably not, because
-  the displayhook also has to handle the Out prompt display. On the other hand
-  we could put that information into the metadata section.
-
 Message type: ``display_data``::
 
     content = {
@@ -913,7 +909,10 b' to update a single namespace with subsequent results.'
 Python inputs
 -------------
 
-These messages are the re-broadcast of the ``execute_request``.
+To let all frontends know what code is being executed at any given time, these
+messages contain a re-broadcast of the ``code`` portion of an
+:ref:`execute_request <execute>`, along with the :ref:`execution_count
+<execution_counter>`.
 
 Message type: ``pyin``::