Merge pull request #280 from craigcitro/doc

Clarify recommended use of metadata in docs.

Author: minrk

docs/api/kernelspec.rst

@@ -30,6 +30,12 @@ kernelspec - discovering kernels
       Additional kernel-specific metadata; clients can use this as needed,
       for instance to aid in kernel selection and filtering.
 
+      Metadata added here should be namespaced for the tool reading and
+      writing that metadata. Concretely, if you're adding a new field called
+      :code:`supported_versions` which your tool recognizes, then you should
+      add it as :code:`"mytool": {"supported_versions": [1, 2]}`, **not** as a
+      top-level field called :code:`supported_versions`.
+
    .. attribute:: resource_dir
 
       The path to the directory with this kernel's resources, such as icons.

docs/kernels.rst

@@ -136,7 +136,8 @@ JSON serialised dictionary containing the following keys and values:
   These will be added to the current environment variables before the kernel is
   started.
 - **metadata** (optional): A dictionary of additional attributes about this
-  kernel; used by clients to aid clients in kernel selection.
+  kernel; used by clients to aid clients in kernel selection. Metadata added
+  here should be namespaced for the tool reading and writing that metadata.
 
 For example, the kernel.json file for IPython looks like this::