Finish renaming description units to object (description)s.

10 files changed, 39 insertions, 34 deletions

diff --git a/doc/concepts.rst b/doc/concepts.rst
index 277672111..212b4c7cc 100644
--- a/doc/concepts.rst
+++ b/doc/concepts.rst
@@ -166,7 +166,7 @@ The special document names (and pages generated for them) are:
   respectively.
 
   The general index is populated with entries from modules, all index-generating
-  :ref:`description units <desc-units>`, and from :dir:`index` directives.
+  :ref:`object descriptions <desc-units>`, and from :dir:`index` directives.
 
   The module index contains one entry per :dir:`module` directive.
 
diff --git a/doc/config.rst b/doc/config.rst
index 47fc2bdd0..529f9cf8d 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -298,8 +298,8 @@ Project information
 .. confval:: add_module_names
 
    A boolean that decides whether module names are prepended to all
-   :term:`description unit` titles, e.g. for :dir:`function` directives.
-   Default is ``True``.
+   :term:`object` names (for object types where a "module" of some kind is
+   defined), e.g. for :dir:`function` directives.  Default is ``True``.
 
 .. confval:: show_authors
 
diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst
index 0a3dae8fb..754f22eb4 100644
--- a/doc/ext/appapi.rst
+++ b/doc/ext/appapi.rst
@@ -123,26 +123,28 @@ the following public API:
 
    .. versionadded:: 0.6
 
-.. method:: Sphinx.add_description_unit(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None)
+.. method:: Sphinx.add_object_type(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None, objname='')
 
-   This method is a very convenient way to add a new type of information that
+   This method is a very convenient way to add a new :term:`object` type that
    can be cross-referenced.  It will do this:
 
-   * Create a new directive (called *directivename*) for a :term:`description
-     unit`.  It will automatically add index entries if *indextemplate* is
-     nonempty; if given, it must contain exactly one instance of ``%s``.  See
-     the example below for how the template will be interpreted.
+   * Create a new directive (called *directivename*) for documenting an object.
+     It will automatically add index entries if *indextemplate* is nonempty; if
+     given, it must contain exactly one instance of ``%s``.  See the example
+     below for how the template will be interpreted.
    * Create a new role (called *rolename*) to cross-reference to these
-     description units.
+     object descriptions.
    * If you provide *parse_node*, it must be a function that takes a string and
      a docutils node, and it must populate the node with children parsed from
      the string.  It must then return the name of the item to be used in
      cross-referencing and index entries.  See the :file:`ext.py` file in the
      source for this documentation for an example.
+   * The *objname* (if not given, will default to *directivename*) names the
+     type of object.  It is used when listing objects, e.g. in search results.
 
    For example, if you have this call in a custom Sphinx extension::
 
-      app.add_description_unit('directive', 'dir', 'pair: %s; directive')
+      app.add_object_type('directive', 'dir', 'pair: %s; directive')
 
    you can use this markup in your documents::
 
@@ -164,12 +166,15 @@ the following public API:
    ``docutils.nodes.emphasis`` or ``docutils.nodes.strong`` -- you can also use
    ``docutils.nodes.generated`` if you want no further text decoration).
 
-   For the role content, you have the same options as for standard Sphinx roles
-   (see :ref:`xref-syntax`).
+   For the role content, you have the same syntactical possibilities as for
+   standard Sphinx roles (see :ref:`xref-syntax`).
 
-.. method:: Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None)
+   This method is also available under the deprecated alias
+   :meth:`add_description_unit`.
 
-   This method is very similar to :meth:`add_description_unit` except that the
+.. method:: Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None, objname='')
+
+   This method is very similar to :meth:`add_object_type` except that the
    directive it generates must be empty, and will produce no output.
 
    That means that you can add semantic targets to your sources, and refer to
diff --git a/doc/glossary.rst b/doc/glossary.rst
index 7ec787ff5..13316900b 100644
--- a/doc/glossary.rst
+++ b/doc/glossary.rst
@@ -19,17 +19,17 @@ Glossary
       the :term:`source directory`, but can be set differently with the **-c**
       command-line option.
 
-   description unit
-      The basic building block of Sphinx documentation.  Every "description
-      directive" (e.g. :dir:`function` or :dir:`describe`) creates such a unit;
-      and most units can be cross-referenced to.
-
    environment
       A structure where information about all documents under the root is saved,
       and used for cross-referencing.  The environment is pickled after the
       parsing stage, so that successive runs only need to read and parse new and
       changed documents.
 
+   object
+      The basic building block of Sphinx documentation.  Every "object
+      directive" (e.g. :dir:`function` or :dir:`object`) creates such a block;
+      and most objects can be cross-referenced to.
+
    source directory
       The directory which, including its subdirectories, contains all source
       files for one Sphinx project.
diff --git a/doc/markup/desc.rst b/doc/markup/desc.rst
index 058b5137d..4df9f6213 100644
--- a/doc/markup/desc.rst
+++ b/doc/markup/desc.rst
@@ -67,10 +67,12 @@ The directives you can use for module declarations are:
 
 .. _desc-units:
 
-Object description units
-------------------------
+Object descriptions
+-------------------
 
-There are a number of directives used to describe specific features provided by
+.. XXX generalize for domains
+
+There are a number of directives used to describe specific objects provided by
 modules.  Each directive requires one or more signatures to provide basic
 information about what is being described, and the content should be the
 description.  The basic version makes entries in the general index; if no index
@@ -243,7 +245,7 @@ Info field lists
 
 .. versionadded:: 0.4
 
-Inside description unit directives, reST field lists with these fields are
+Inside object description directives, reST field lists with these fields are
 recognized and formatted nicely:
 
 * ``param``, ``parameter``, ``arg``, ``argument``, ``key``, ``keyword``:
@@ -340,8 +342,8 @@ There is a set of directives allowing documenting command-line programs:
    .. versionadded:: 0.5
 
 
-Custom description units
-~~~~~~~~~~~~~~~~~~~~~~~~
+Custom object types
+~~~~~~~~~~~~~~~~~~~
 
 There is also a generic version of these directives:
 
@@ -356,4 +358,4 @@ There is also a generic version of these directives:
          Describes a Python bytecode instruction.
 
 Extensions may add more directives like that, using the
-:func:`~sphinx.application.Sphinx.add_description_unit` method.
+:func:`~sphinx.application.Sphinx.add_object_type` method.
diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py
index 71a26febc..08d6feaaf 100644
--- a/sphinx/addnodes.py
+++ b/sphinx/addnodes.py
@@ -14,7 +14,7 @@ from docutils import nodes
 # index markup
 class index(nodes.Invisible, nodes.Inline, nodes.TextElement): pass
 
-# domain-specific object description units (class, function etc.)
+# domain-specific object descriptions (class, function etc.)
 
 # parent node for signature and content
 class desc(nodes.Admonition, nodes.Element): pass
diff --git a/sphinx/application.py b/sphinx/application.py
index af10bb7e2..55998058e 100644
--- a/sphinx/application.py
+++ b/sphinx/application.py
@@ -382,7 +382,6 @@ class Sphinx(object):
 
     def add_object_type(self, directivename, rolename, indextemplate='',
                         parse_node=None, ref_nodeclass=None, objname=''):
-        # XXX document objname
         StandardDomain.object_types[directivename] = \
             ObjType(objname or directivename, rolename)
         # create a subclass of GenericObject as the new directive
@@ -398,7 +397,6 @@ class Sphinx(object):
 
     def add_crossref_type(self, directivename, rolename, indextemplate='',
                           ref_nodeclass=None, objname=''):
-        # XXX document objname
         StandardDomain.object_types[directivename] = \
             ObjType(objname or directivename, rolename)
         # create a subclass of Target as the new directive
diff --git a/sphinx/domains/std.py b/sphinx/domains/std.py
index f2da7d116..37ae9378b 100644
--- a/sphinx/domains/std.py
+++ b/sphinx/domains/std.py
@@ -30,7 +30,7 @@ option_desc_re = re.compile(
 
 class GenericObject(ObjectDescription):
     """
-    A generic x-ref directive registered with Sphinx.add_description_unit().
+    A generic x-ref directive registered with Sphinx.add_object_type().
     """
     indextemplate = ''
     parse_node = None
diff --git a/sphinx/environment.py b/sphinx/environment.py
index 81c044d83..f309823d1 100644
--- a/sphinx/environment.py
+++ b/sphinx/environment.py
@@ -888,7 +888,7 @@ class BuildEnvironment:
             if name.isdigit() or node.has_key('refuri') or \
                    node.tagname.startswith('desc_'):
                 # ignore footnote labels, labels automatically generated from a
-                # link and description units
+                # link and object descriptions
                 continue
             if name in self.labels:
                 self.warn(docname, 'duplicate label %s, ' % name +
diff --git a/tests/root/conf.py b/tests/root/conf.py
index dbb2bca7e..13b267994 100644
--- a/tests/root/conf.py
+++ b/tests/root/conf.py
@@ -85,5 +85,5 @@ def setup(app):
     app.add_config_value('value_from_conf_py', 42, False)
     app.add_directive('funcdir', functional_directive, opt=lambda x: x)
     app.add_directive('clsdir', ClassDirective)
-    app.add_description_unit('userdesc', 'userdescrole', '%s (userdesc)',
-                             userdesc_parse)
+    app.add_object_type('userdesc', 'userdescrole', '%s (userdesc)',
+                        userdesc_parse, objname='user desc')