2 files changed, 16 insertions, 6 deletions

diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst
index a82f33a80..481688acf 100644
--- a/doc/extdev/index.rst
+++ b/doc/extdev/index.rst
@@ -18,15 +18,25 @@ imports this module and executes its ``setup()`` function, which in turn
 notifies Sphinx of everything the extension offers -- see the extension tutorial
 for examples.
 
-.. versionadded:: 1.3
-   The ``setup()`` function can return a string, this is treated by Sphinx as
-   the version of the extension and used for informational purposes such as the
-   traceback file when an exception occurs.
-
 The configuration file itself can be treated as an extension if it contains a
 ``setup()`` function.  All other extensions to load must be listed in the
 :confval:`extensions` configuration value.
 
+Extension metadata
+------------------
+
+.. versionadded:: 1.3
+
+The ``setup()`` function can return a dictionary.  This is treated by Sphinx
+as metadata of the extension.  Metadata keys currently recognized are:
+
+* ``'version'``: a string that identifies the extension version.  It is used for
+  extension version requirement checking (see :confval:`needs_extensions`) and
+  informational purposes.  If not given, ``"unknown version"`` is substituted.
+
+APIs used for writing extensions
+--------------------------------
+
 .. toctree::
 
    tutorial
diff --git a/doc/extdev/tutorial.rst b/doc/extdev/tutorial.rst
index 8f1773cdf..e7912406a 100644
--- a/doc/extdev/tutorial.rst
+++ b/doc/extdev/tutorial.rst
@@ -162,7 +162,7 @@ new Python module called :file:`todo.py` and add the setup function::
        app.connect('doctree-resolved', process_todo_nodes)
        app.connect('env-purge-doc', purge_todos)
 
-       return '0.1'   # identifies the version of our extension
+       return {'version': '0.1'}   # identifies the version of our extension
 
 The calls in this function refer to classes and functions not yet written.  What
 the individual calls do is the following: