format-related docstrings!

IPython/core/displayhook.py

@@ -145,11 +145,14 b' class DisplayHook(Configurable):'
 
         Returns
         -------
-        format_data : dict
-            A :class:`dict` whose keys are valid MIME types and values are
+        (format_dict, md_dict) : dict
+            format_dict is a :class:`dict` whose keys are valid MIME types and values are
             JSON'able raw data for that MIME type. It is recommended that
             all return values of this should always include the "text/plain"
             MIME type representation of the object.
+            md_dict is a :class:`dict` with the same MIME type keys
+            of metadata associated with each output.
+            
         """
         return self.shell.display_formatter.format(result)
 
@@ -165,6 +168,8 b' class DisplayHook(Configurable):'
         ----------
         format_dict : dict
             The format dict for the object passed to `sys.displayhook`.
+        md_dict : dict (optional)
+            The metadata dict to be associated with the display data.
         """
         # We want to print because we want to always make sure we have a
         # newline, even if all the prompt separators are ''. This is the

IPython/core/displaypub.py

@@ -98,7 +98,9 b' class DisplayPublisher(Configurable):'
         metadata : dict
             A dictionary for metadata related to the data. This can contain
             arbitrary key, value pairs that frontends can use to interpret
-            the data.
+            the data.  Metadata specific to each mime-type can be specified
+            in the metadata dict with the same mime-type keys as
+            the data itself.
         """
 
         # The default is to simply write the plain text data using io.stdout.
@@ -149,8 +151,9 b' def publish_display_data(source, data, metadata=None):'
     metadata : dict
         A dictionary for metadata related to the data. This can contain
         arbitrary key, value pairs that frontends can use to interpret
-        the data.
-    """
+        the data. mime-type keys matching those in data can be used
+        to specify metadata about particular representations.
+        """
     from IPython.core.interactiveshell import InteractiveShell
     InteractiveShell.instance().display_pub.publish(
         source,

IPython/core/formatters.py

@@ -127,12 +127,16 b' class DisplayFormatter(Configurable):'
 
         Returns
         -------
-        format_dict : dict
-            A dictionary of key/value pairs, one or each format that was
+        (format_dict, metadata_dict) : tuple of two dicts
+        
+            format_dict is a dictionary of key/value pairs, one of each format that was
             generated for the object. The keys are the format types, which
             will usually be MIME type strings and the values and JSON'able
             data structure containing the raw data for the representation in
             that format.
+            
+            metadata_dict is a dictionary of metadata about each mime-type output.
+            Its keys will be a strict subset of the keys in format_dict.
         """
         format_dict = {}
         md_dict = {}