Decl styling, docs and restructuring

3 files changed, 74 insertions, 28 deletions

diff --git a/doc/extdev/nodes.rst b/doc/extdev/nodes.rst
index 3976de4c7..d327e1cb0 100644
--- a/doc/extdev/nodes.rst
+++ b/doc/extdev/nodes.rst
@@ -8,18 +8,31 @@ Doctree node classes added by Sphinx
 Nodes for domain-specific object descriptions
 ---------------------------------------------
 
+Top-level nodes
+...............
+
+These nodes form the top-most levels of object descriptions.
+
 .. autoclass:: desc
 .. autoclass:: desc_signature
 .. autoclass:: desc_signature_line
+.. autoclass:: desc_content
+
+Nodes for high-level structure in signatures
+............................................
+
+These nodes occur in in non-multiline :py:class:`desc_signature` nodes
+and in :py:class:`desc_signature_line` nodes.
+
+.. autoclass:: desc_name
 .. autoclass:: desc_addname
+
 .. autoclass:: desc_type
 .. autoclass:: desc_returns
-.. autoclass:: desc_name
 .. autoclass:: desc_parameterlist
 .. autoclass:: desc_parameter
 .. autoclass:: desc_optional
 .. autoclass:: desc_annotation
-.. autoclass:: desc_content
 
 New admonition-like constructs
 ------------------------------
diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py
index 3200e5e47..f818e496d 100644
--- a/sphinx/addnodes.py
+++ b/sphinx/addnodes.py
@@ -115,24 +115,32 @@ class toctree(nodes.General, nodes.Element, translatable):
         return messages
 
 
-# domain-specific object descriptions (class, function etc.)
+#############################################################
+# Domain-specific object descriptions (class, function etc.)
+#############################################################
+
+# Top-level nodes
+#################
 
 class desc(nodes.Admonition, nodes.Element):
-    """Node for object descriptions.
+    """Node for a list of object signatures and a common description of them.
+
+    Contains one or more :py:class:`desc_signature` nodes
+    and then a single :py:class:`desc_content` node.
+
+    This node always has two classes:
 
-    This node is similar to a "definition list" with one definition.  It
-    contains one or more ``desc_signature`` and a ``desc_content``.
+    - The name of the domain it belongs to, e.g., ``py`` or ``cpp``.
+    - The name of the object type in the domain, e.g., ``function``.
     """
 
 
 class desc_signature(nodes.Part, nodes.Inline, nodes.TextElement):
-    """Node for object signatures.
+    """Node for a single object signature.
 
-    The "term" part of the custom Sphinx definition list.
-
-    As default the signature is a single line signature,
-    but set ``is_multiline = True`` to describe a multi-line signature.
-    In that case all child nodes must be ``desc_signature_line`` nodes.
+    As default the signature is a single-line signature.
+    Set ``is_multiline = True`` to describe a multi-line signature.
+    In that case all child nodes must be :py:class:`desc_signature_line` nodes.
     """
 
     @property
@@ -144,22 +152,40 @@ class desc_signature(nodes.Part, nodes.Inline, nodes.TextElement):
 
 
 class desc_signature_line(nodes.Part, nodes.Inline, nodes.FixedTextElement):
-    """Node for a line in a multi-line object signatures.
+    """Node for a line in a multi-line object signature.
 
-    It should only be used in a ``desc_signature`` with ``is_multiline`` set.
+    It should only be used as a child of a :py:class:`desc_signature`
+    with ``is_multiline`` set to ``True``.
     Set ``add_permalink = True`` for the line that should get the permalink.
     """
     sphinx_line_type = ''
 
 
+class desc_content(nodes.General, nodes.Element):
+    """Node for object description content.
+
+    Must be the last child node in a :py:class:`desc` node.
+    """
+
+# Nodes for high-level structure in signatures
+##############################################
+
 # nodes to use within a desc_signature or desc_signature_line
 
 class desc_name(nodes.Part, nodes.Inline, nodes.FixedTextElement):
-    """Node for the main object name."""
+    """Node for the main object name.
+
+    For example, in the declaration of a Python class ``MyModule.MyClass``,
+    the main name is ``MyClass``.
+    """
 
 
 class desc_addname(nodes.Part, nodes.Inline, nodes.FixedTextElement):
-    """Node for additional name parts (module name, class name)."""
+    """Node for additional name parts for an object.
+
+    For example, in the declaration of a Python class ``MyModule.MyClass``,
+    the additional name part is ``MyModule.``.
+    """
 
 
 # compatibility alias
@@ -201,12 +227,8 @@ class desc_annotation(nodes.Part, nodes.Inline, nodes.FixedTextElement):
     """Node for signature annotations (not Python 3-style annotations)."""
 
 
-class desc_content(nodes.General, nodes.Element):
-    """Node for object description content.
-
-    This is the "definition" part of the custom Sphinx definition list.
-    """
-
+# Leaf nodes for markup of text fragments
+#########################################
 
 # Signature text elements, generally translated to node.inline
 # in SigElementFallbackTransform.
@@ -281,6 +303,7 @@ SIG_ELEMENTS = [desc_sig_space,
                 desc_sig_literal_number, desc_sig_literal_string, desc_sig_literal_char]
 
 
+###############################################################
 # new admonition-like constructs
 
 class versionmodified(nodes.Admonition, nodes.TextElement):
diff --git a/sphinx/writers/html5.py b/sphinx/writers/html5.py
index fa7360c4e..745e76b38 100644
--- a/sphinx/writers/html5.py
+++ b/sphinx/writers/html5.py
@@ -78,6 +78,13 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
     def depart_start_of_file(self, node: Element) -> None:
         self.docnames.pop()
 
+    #############################################################
+    # Domain-specific object descriptions
+    #############################################################
+
+    # Top-level nodes for descriptions
+    ##################################
+
     def visit_desc(self, node: Element) -> None:
         self.body.append(self.starttag(node, 'dl', CLASS=node['objtype']))
 
@@ -104,6 +111,15 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
             self.add_permalink_ref(node.parent, _('Permalink to this definition'))
         self.body.append('<br />')
 
+    # Nodes for high-level structure in signatures
+    ##############################################
+
+    def visit_desc_name(self, node: Element) -> None:
+        self.body.append(self.starttag(node, 'code', '', CLASS='sig-name descname'))
+
+    def depart_desc_name(self, node: Element) -> None:
+        self.body.append('</code>')
+
     def visit_desc_addname(self, node: Element) -> None:
         self.body.append(self.starttag(node, 'code', '', CLASS='sig-prename descclassname'))
 
@@ -122,12 +138,6 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
     def depart_desc_returns(self, node: Element) -> None:
         pass
 
-    def visit_desc_name(self, node: Element) -> None:
-        self.body.append(self.starttag(node, 'code', '', CLASS='sig-name descname'))
-
-    def depart_desc_name(self, node: Element) -> None:
-        self.body.append('</code>')
-
     def visit_desc_parameterlist(self, node: Element) -> None:
         self.body.append('<span class="sig-paren">(</span>')
         self.first_param = 1