From 65081218ce41b1bac03de567ae8b3cde08094b72 Mon Sep 17 00:00:00 2001
From: Arthur Milchior <arthur@milchior.fr>
Date: Sat, 24 Sep 2022 16:30:57 +0200
Subject: [PATCH] Docstring clarifications (#9877)

Co-authored-by: Jakob Lykke Andersen <jakobandersen@users.noreply.github.com>
Co-authored-by: Takeshi KOMIYA <i.tkomiya@gmail.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
---
 sphinx/addnodes.py                  | 43 +++++++-------
 sphinx/application.py               | 90 +++++++++++++++++------------
 sphinx/builders/latex/transforms.py |  2 +-
 sphinx/domains/std.py               |  6 +-
 sphinx/extension.py                 |  9 ++-
 5 files changed, 85 insertions(+), 65 deletions(-)

diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py
index e23f570d7..e22ce5fa2 100644
--- a/sphinx/addnodes.py
+++ b/sphinx/addnodes.py
@@ -1,4 +1,4 @@
-"""Additional docutils nodes."""
+"""Document tree nodes that Sphinx defines on top of those in Docutils."""
 
 from typing import TYPE_CHECKING, Any, Dict, List, Optional, Sequence
 
@@ -119,7 +119,7 @@ class toctree(nodes.General, nodes.Element, translatable):
 #############################################################
 
 class _desc_classes_injector(nodes.Element, not_smartquotable):
-    """Helper base class for injecting a fixes list of classes.
+    """Helper base class for injecting a fixed list of classes.
 
     Use as the first base class.
     """
@@ -390,7 +390,7 @@ class index(nodes.Invisible, nodes.Inline, nodes.TextElement):
 
 
 class centered(nodes.Part, nodes.TextElement):
-    """Deprecated."""
+    """This node is deprecated."""
 
 
 class acks(nodes.Element):
@@ -455,13 +455,18 @@ class pending_xref(nodes.Inline, nodes.Element):
 
 
 class pending_xref_condition(nodes.Inline, nodes.TextElement):
-    """Node for cross-references that are used to choose appropriate
-    content of the reference by conditions on the resolving phase.
+    """Node representing a potential way to create a cross-reference and the
+    condition in which this way should be used.
 
-    When the :py:class:`pending_xref` node contains one or more
-    **pending_xref_condition** nodes, the cross-reference resolver
-    should choose the content of the reference using defined conditions
-    in ``condition`` attribute of each pending_xref_condition nodes::
+    This node is only allowed to be placed under a :py:class:`pending_xref`
+    node.  A **pending_xref** node must contain either no **pending_xref_condition**
+    nodes or it must only contains **pending_xref_condition** nodes.
+
+    The cross-reference resolver will replace a :py:class:`pending_xref` which
+    contains **pending_xref_condition** nodes by the content of exactly one of
+    those **pending_xref_condition** nodes' content. It uses the **condition**
+    attribute to decide which **pending_xref_condition** node's content to
+    use. For example, let us consider how the cross-reference resolver acts on::
 
         <pending_xref refdomain="py" reftarget="io.StringIO ...>
             <pending_xref_condition condition="resolved">
@@ -471,32 +476,26 @@ class pending_xref_condition(nodes.Inline, nodes.TextElement):
                 <literal>
                     io.StringIO
 
-    After the processing of cross-reference resolver, one of the content node
-    under pending_xref_condition node is chosen by its condition and to be
-    removed all of pending_xref_condition nodes::
+    If the cross-reference resolver successfully resolves the cross-reference,
+    then it rewrites the **pending_xref** as::
 
-        # When resolved the cross-reference successfully
         <reference>
             <literal>
                 StringIO
 
-        # When resolution is failed
+    Otherwise, if the cross-reference resolution failed, it rewrites the
+    **pending_xref** as::
+
         <reference>
             <literal>
                 io.StringIO
 
-    .. note:: This node is only allowed to be placed under pending_xref node.
-              It is not allows to place it under other nodes.  In addition,
-              pending_xref node must contain only pending_xref_condition
-              nodes if it contains one or more pending_xref_condition nodes.
-
-    The pending_xref_condition node should have **condition** attribute.
+    The **pending_xref_condition** node should have **condition** attribute.
     Domains can be store their individual conditions into the attribute to
     filter contents on resolving phase.  As a reserved condition name,
     ``condition="*"`` is used for the fallback of resolution failure.
     Additionally, as a recommended condition name, ``condition="resolved"``
-    is used for the representation of resolstion success in the intersphinx
-    module.
+    represents a resolution success in the intersphinx module.
 
     .. versionadded:: 4.0
     """
diff --git a/sphinx/application.py b/sphinx/application.py
index 565125b1e..10c03a268 100644
--- a/sphinx/application.py
+++ b/sphinx/application.py
@@ -639,8 +639,9 @@ class Sphinx:
 
         :param name: The name of the directive
         :param cls: A directive class
-        :param override: If true, install the directive forcedly even if another directive
+        :param override: If false, do not install it if another directive
                          is already installed as the same name
+                         If true, unconditionally install the directive.
 
         For example, a custom directive named ``my-directive`` would be added
         like this:
@@ -687,8 +688,9 @@ class Sphinx:
 
         :param name: The name of role
         :param role: A role function
-        :param override: If true, install the role forcedly even if another role is already
-                         installed as the same name
+        :param override: If false, do not install it if another role
+                         is already installed as the same name
+                         If true, unconditionally install the role.
 
         For more details about role functions, see `the Docutils docs
         <https://docutils.sourceforge.io/docs/howto/rst-roles.html>`__ .
@@ -708,8 +710,9 @@ class Sphinx:
         Register a Docutils role that does nothing but wrap its contents in the
         node given by *nodeclass*.
 
-        If *override* is True, the given *nodeclass* is forcedly installed even if
-        a role named as *name* is already installed.
+        :param override: If false, do not install it if another role
+                         is already installed as the same name
+                         If true, unconditionally install the role.
 
         .. versionadded:: 0.6
         .. versionchanged:: 1.8
@@ -728,8 +731,9 @@ class Sphinx:
         """Register a domain.
 
         :param domain: A domain class
-        :param override: If true, install the domain forcedly even if another domain
+        :param override: If false, do not install it if another domain
                          is already installed as the same name
+                         If true, unconditionally install the domain.
 
         .. versionadded:: 1.0
         .. versionchanged:: 1.8
@@ -747,8 +751,9 @@ class Sphinx:
         :param domain: The name of target domain
         :param name: A name of directive
         :param cls: A directive class
-        :param override: If true, install the directive forcedly even if another directive
+        :param override: If false, do not install it if another directive
                          is already installed as the same name
+                         If true, unconditionally install the directive.
 
         .. versionadded:: 1.0
         .. versionchanged:: 1.8
@@ -766,8 +771,9 @@ class Sphinx:
         :param domain: The name of the target domain
         :param name: The name of the role
         :param role: The role function
-        :param override: If true, install the role forcedly even if another role is already
-                         installed as the same name
+        :param override: If false, do not install it if another role
+                         is already installed as the same name
+                         If true, unconditionally install the role.
 
         .. versionadded:: 1.0
         .. versionchanged:: 1.8
@@ -783,8 +789,9 @@ class Sphinx:
 
         :param domain: The name of the target domain
         :param index: The index class
-        :param override: If true, install the index forcedly even if another index is
-                         already installed as the same name
+        :param override: If false, do not install it if another index
+                         is already installed as the same name
+                         If true, unconditionally install the index.
 
         .. versionadded:: 1.0
         .. versionchanged:: 1.8
@@ -889,8 +896,10 @@ class Sphinx:
         (Of course, the element following the ``topic`` directive needn't be a
         section.)
 
-        If *override* is True, the given crossref_type is forcedly installed even if
-        a crossref_type having the same name is already installed.
+
+        :param override: If false, do not install it if another cross-reference type
+                         is already installed as the same name
+                         If true, unconditionally install the cross-reference type.
 
         .. versionchanged:: 1.8
            Add *override* keyword.
@@ -949,20 +958,22 @@ class Sphinx:
                     loading_method: Optional[str] = None, **kwargs: Any) -> None:
         """Register a JavaScript file to include in the HTML output.
 
-        :param filename: The filename of the JavaScript file.  It must be relative to the HTML
-                         static path, a full URI with scheme, or ``None`` value.  The ``None``
-                         value is used to create inline ``<script>`` tag.  See the description
-                         of *kwargs* below.
-        :param priority: The priority to determine the order of ``<script>`` tag for
-                         JavaScript files.  See list of "prority range for JavaScript
-                         files" below.  If the priority of the JavaScript files it the same
-                         as others, the JavaScript files will be loaded in order of
-                         registration.
-        :param loading_method: The loading method of the JavaScript file.  ``'async'`` or
-                               ``'defer'`` is allowed.
-        :param kwargs: Extra keyword arguments are included as attributes of the ``<script>``
-                       tag.  A special keyword argument ``body`` is given, its value will be
-                       added between the ``<script>`` tag.
+        :param filename: The name of a JavaScript file that the default HTML
+                         template will include. It must be relative to the HTML
+                         static path, or a full URI with scheme, or ``None`` .
+                         The ``None`` value is used to create an inline
+                         ``<script>`` tag.  See the description of *kwargs*
+                         below.
+        :param priority: Files are included in ascending order of priority. If
+                         multiple JavaScript files have the same priority,
+                         those files will be included in order of registration.
+                         See list of "prority range for JavaScript files" below.
+        :param loading_method: The loading method for the JavaScript file.
+                               Either ``'async'`` or ``'defer'`` are allowed.
+        :param kwargs: Extra keyword arguments are included as attributes of the
+                       ``<script>`` tag.  If the special keyword argument
+                       ``body`` is given, its value will be added as the content
+                       of the  ``<script>`` tag.
 
         Example::
 
@@ -1015,14 +1026,15 @@ class Sphinx:
     def add_css_file(self, filename: str, priority: int = 500, **kwargs: Any) -> None:
         """Register a stylesheet to include in the HTML output.
 
-        :param filename: The filename of the CSS file.  It must be relative to the HTML
+        :param filename: The name of a CSS file that the default HTML
+                         template will include. It must be relative to the HTML
                          static path, or a full URI with scheme.
-        :param priority: The priority to determine the order of ``<link>`` tag for the
-                         CSS files.  See list of "prority range for CSS files" below.
-                         If the priority of the CSS files it the same as others, the
-                         CSS files will be loaded in order of registration.
-        :param kwargs: Extra keyword arguments are included as attributes of the ``<link>``
-                       tag.
+        :param priority: Files are included in ascending order of priority. If
+                         multiple CSS files have the same priority,
+                         those files will be included in order of registration.
+                         See list of "prority range for CSS files" below.
+        :param kwargs: Extra keyword arguments are included as attributes of the
+                       ``<link>`` tag.
 
         Example::
 
@@ -1191,8 +1203,9 @@ class Sphinx:
         Same as :confval:`source_suffix`.  The users can override this
         using the config setting.
 
-        If *override* is True, the given *suffix* is forcedly installed even if
-        the same suffix is already installed.
+        :param override: If false, do not install it the same suffix
+                         is already installed.
+                         If true, unconditionally install the suffix.
 
         .. versionadded:: 1.8
         """
@@ -1201,8 +1214,9 @@ class Sphinx:
     def add_source_parser(self, parser: Type[Parser], override: bool = False) -> None:
         """Register a parser class.
 
-        If *override* is True, the given *parser* is forcedly installed even if
-        a parser for the same suffix is already installed.
+        :param override: If false, do not install it if another parser
+                         is already installed for the same suffix.
+                         If true, unconditionally install the parser.
 
         .. versionadded:: 1.4
         .. versionchanged:: 1.8
diff --git a/sphinx/builders/latex/transforms.py b/sphinx/builders/latex/transforms.py
index e996250f7..de3f3ff03 100644
--- a/sphinx/builders/latex/transforms.py
+++ b/sphinx/builders/latex/transforms.py
@@ -30,7 +30,7 @@ class FootnoteDocnameUpdater(SphinxTransform):
 
 
 class SubstitutionDefinitionsRemover(SphinxPostTransform):
-    """Remove ``substitution_definition node from doctrees."""
+    """Remove ``substitution_definition`` nodes from doctrees."""
 
     # should be invoked after Substitutions process
     default_priority = Substitutions.default_priority + 1
diff --git a/sphinx/domains/std.py b/sphinx/domains/std.py
index 6218de6ab..68cab115c 100644
--- a/sphinx/domains/std.py
+++ b/sphinx/domains/std.py
@@ -493,12 +493,12 @@ class ProductionList(SphinxDirective):
         lines = nl_escape_re.sub('', self.arguments[0]).split('\n')
 
         productionGroup = ""
-        i = 0
+        first_rule_seen = False
         for rule in lines:
-            if i == 0 and ':' not in rule:
+            if not first_rule_seen and ':' not in rule:
                 productionGroup = rule.strip()
                 continue
-            i += 1
+            first_rule_seen = True
             try:
                 name, tokens = rule.split(':', 1)
             except ValueError:
diff --git a/sphinx/extension.py b/sphinx/extension.py
index 356b4ab9d..2a984f5b4 100644
--- a/sphinx/extension.py
+++ b/sphinx/extension.py
@@ -34,7 +34,14 @@ class Extension:
 
 
 def verify_needs_extensions(app: "Sphinx", config: Config) -> None:
-    """Verify the required Sphinx extensions are loaded."""
+    """Check that extensions mentioned in :confval:`needs_extensions` satisfy the version
+    requirement, and warn if an extension is not loaded.
+
+    Warns if an extension in :confval:`needs_extension` is not loaded.
+
+    :raises VersionRequirementError: if the version of an extension in
+    :confval:`needs_extension` is unknown or older than the required version.
+    """
     if config.needs_extensions is None:
         return