add some detail to the wire protocol

docs/source/development/messaging.txt

@@ -102,20 +102,28 b' A message is defined by the following four-dictionary structure::'
       # clients can track where messages come from.
       'parent_header' : dict,
 
+      # Any metadata associated with the message.
+      'metadata' : dict,
+      
       # The actual content of the message must be a dict, whose structure
       # depends on the message type.
       'content' : dict,
-      
-      # Any metadata associated with the message.
-      'metadata' : dict,
     }
 
 The Wire Protocol
 =================
 
+
 This message format exists at a high level,
 but does not describe the actual *implementation* at the wire level in zeromq.
 The canonical implementation of the message spec is our :class:`~IPython.kernel.zmq.session.Session` class.
+
+.. note::
+
+    This section should only be relevant to non-Python consumers of the protocol.
+    Python consumers should simply import and use IPython's own implementation of the wire protocol
+    in the :class:`IPython.kernel.zmq.session.Session` object.
+
 Every message is serialized to a sequence of at least six blobs of bytes:
 
 .. sourcecode:: python
@@ -135,13 +143,15 b' Every message is serialized to a sequence of at least six blobs of bytes:'
 The front of the message is the ZeroMQ routing prefix,
 which can be zero or more socket identities.
 This is every piece of the message prior to the delimiter key ``<IDS|MSG>``.
-In the case of IOPub, there should be just one prefix,
-which is the topic for IOPub subscribers, e.g. ``stdout``, ``stderr``, ``pyout``.
+In the case of IOPub, there should be just one prefix component,
+which is the topic for IOPub subscribers, e.g. ``pyout``, ``display_data``.
 
 .. note::
 
     In most cases, the IOPub topics are irrelevant and completely ignored,
     because frontends just subscribe to all topics.
+    The convention used in the IPython kernel is to use the msg_type as the topic,
+    and possibly extra information about the message, e.g. ``pyout`` or ``stream.stdout``
 
 After the delimiter is the `HMAC`_ signature of the message, used for authentication.
 If authentication is disabled, this should be an empty string.
@@ -154,15 +164,28 b' By default, the hashing function used for computing these signatures is sha256.'
     To disable authentication and signature checking,
     set the `key` field of a connection file to an empty string.
 
-The signature is generated by computing the HMAC digest of the concatenation of:
+The signature is the HMAC hex digest of the concatenation of:
 
-- A shared key (from the ``key`` field of a connection file)
+- A shared key (typically the ``key`` field of a connection file)
 - The serialized header dict
 - The serialized parent header dict
 - The serialized metadata dict
 - The serialized content dict
 
-After the signature is the actual message, always in four byte sequences.
+In Python, this is implemented via:
+
+.. sourcecode:: python
+
+    # once:
+    digester = HMAC(key, digestmod=hashlib.sha256)
+    
+    # for each message
+    d = digester.copy()
+    for serialized_dict in (header, parent, metadata, content):
+        d.update(serialized_dict)
+    signature = d.hexdigest()
+
+After the signature is the actual message, always in four frames of bytes.
 The four dictionaries that compose a message are serialized separately,
 in the order of header, parent header, metadata, and content.
 These can be serialized by any function that turns a dict into bytes.