Better variable names

Author: TLouf

sphinx/addnodes.py

@@ -150,7 +150,7 @@ class desc_signature(_desc_classes_injector, nodes.Part, nodes.Inline, nodes.Tex
     """Node for a single object signature.
 
     As default the signature is a single-line signature.
-    Set ``is_multiline = True`` to describe a multi-line signature.
+    Set ``is_multi_line = True`` to describe a multi-line signature.
     In that case all child nodes must be :py:class:`desc_signature_line` nodes.
 
     This node always has the classes ``sig``, ``sig-object``, and the domain it belongs to.
@@ -160,7 +160,7 @@ class desc_signature(_desc_classes_injector, nodes.Part, nodes.Inline, nodes.Tex
 
     @property
     def child_text_separator(self):
-        if self.get('is_multiline'):
+        if self.get('is_multi_line'):
             return ' '
         else:
             return super().child_text_separator
@@ -170,7 +170,7 @@ class desc_signature_line(nodes.Part, nodes.Inline, nodes.FixedTextElement):
     """Node for a line in a multi-line object signature.
 
     It should only be used as a child of a :py:class:`desc_signature`
-    with ``is_multiline`` set to ``True``.
+    with ``is_multi_line`` set to ``True``.
     Set ``add_permalink = True`` for the line that should get the permalink.
     """
     sphinx_line_type = ''
@@ -249,8 +249,7 @@ def astext(self):
         return f'({super().astext()})'
 
 
-class desc_parameterline(nodes.General, nodes.Element):
-    """Node for a parameter line."""
+class desc_parameter_line(nodes.General, nodes.Element):
 
 
 class desc_parameter(nodes.Part, nodes.Inline, nodes.FixedTextElement):

sphinx/domains/c.py

@@ -691,11 +691,11 @@ def __init__(
         self,
         args: list[ASTFunctionParameter],
         attrs: ASTAttributeList,
-        multiline: bool = False,
+        multi_line: bool = False,
     ) -> None:
         self.args = args
         self.attrs = attrs
-        self.multiline = multiline
+        self.multi_line = multi_line
 
     @property
     def function_params(self) -> list[ASTFunctionParameter]:
@@ -719,17 +719,17 @@ def _stringify(self, transform: StringifyTransform) -> str:
     def describe_signature(self, signode: TextElement, mode: str,
                            env: BuildEnvironment, symbol: Symbol) -> None:
         verify_description_mode(mode)
-        multiline = self.multiline
+        multi_line = self.multi_line
         # only use the desc_parameterlist for the outer list, not for inner lists
         if mode == 'lastIsName':
             paramlist = addnodes.desc_parameterlist()
-            paramlist['is_multiline'] = multiline
+            paramlist['is_multi_line'] = multi_line
             for arg in self.args:
-                param_node = addnodes.desc_parameterline() if multiline else paramlist
+                param_node = addnodes.desc_parameter_line() if multi_line else paramlist
                 param = addnodes.desc_parameter('', '', noemph=True)
                 arg.describe_signature(param, 'param', env, symbol=symbol)
                 param_node += param
-                if multiline:
+                if multi_line:
                     paramlist += param_node
             signode += paramlist
         else:
@@ -1468,7 +1468,7 @@ def describe_signature(self, signode: TextElement, mode: str,
         assert self.symbol
         # The caller of the domain added a desc_signature node.
         # Always enable multiline:
-        signode['is_multiline'] = True
+        signode['is_multi_line'] = True
         # Put each line in a desc_signature_line node.
         mainDeclNode = addnodes.desc_signature_line()
         mainDeclNode.sphinx_line_type = 'declarator'
@@ -2681,7 +2681,7 @@ def _parse_parameters(self, paramMode: str) -> ASTParameters | None:
                         'got "%s".' % self.current_char)
 
         attrs = self._parse_attribute_list()
-        return ASTParameters(args, attrs, multiline=self.multiline)
+        return ASTParameters(args, attrs, multi_line=self.multi_line)
 
     def _parse_decl_specs_simple(
         self, outer: str | None, typed: bool
@@ -3160,7 +3160,7 @@ class CObject(ObjectDescription[ASTDeclaration]):
     option_spec: OptionSpec = {
         'noindexentry': directives.flag,
         'nocontentsentry': directives.flag,
-        'singlelinesig': directives.flag,
+        'single-line-signature': directives.flag,
     }
 
     def _add_enumerator_to_parent(self, ast: ASTDeclaration) -> None:
@@ -3267,14 +3267,14 @@ def handle_signature(self, sig: str, signode: TextElement) -> ASTDeclaration:
         parentSymbol: Symbol = self.env.temp_data['c:parent_symbol']
 
         max_len = self.env.config.c_maximum_signature_line_length
-        multiline = (
+        multi_line = (
             max_len >= 0
-            and 'singlelinesig' not in self.options
+            and 'single-line-signature' not in self.options
             and len(sig) > max_len
         )
-        signode['is_multiline'] = multiline
+        signode['is_multi_line'] = multi_line
         parser = DefinitionParser(
-            sig, location=signode, config=self.env.config, multiline=multiline
+            sig, location=signode, config=self.env.config, multi_line=multi_line
         )
         try:
             ast = self.parse_definition(parser)

sphinx/domains/cpp.py

@@ -2049,7 +2049,7 @@ def __init__(self, args: list[ASTFunctionParameter], volatile: bool, const: bool
                  refQual: str | None, exceptionSpec: ASTNoexceptSpec,
                  trailingReturn: ASTType,
                  override: bool, final: bool, attrs: ASTAttributeList,
-                 initializer: str | None, multiline: bool = False) -> None:
+                 initializer: str | None, multi_line: bool = False) -> None:
         self.args = args
         self.volatile = volatile
         self.const = const
@@ -2060,7 +2060,7 @@ def __init__(self, args: list[ASTFunctionParameter], volatile: bool, const: bool
         self.final = final
         self.attrs = attrs
         self.initializer = initializer
-        self.multiline = multiline
+        self.multi_line = multi_line
 
     @property
     def function_params(self) -> list[ASTFunctionParameter]:
@@ -2130,17 +2130,17 @@ def _stringify(self, transform: StringifyTransform) -> str:
     def describe_signature(self, signode: TextElement, mode: str,
                            env: BuildEnvironment, symbol: Symbol) -> None:
         verify_description_mode(mode)
-        multiline = self.multiline
+        multi_line = self.multi_line
         # only use the desc_parameterlist for the outer list, not for inner lists
         if mode == 'lastIsName':
             paramlist = addnodes.desc_parameterlist()
-            paramlist['is_multiline'] = multiline
+            paramlist['is_multi_line'] = multi_line
             for arg in self.args:
-                param_node = addnodes.desc_parameterline() if multiline else paramlist
+                param_node = addnodes.desc_parameterline() if multi_line else paramlist
                 param = addnodes.desc_parameter('', '', noemph=True)
                 arg.describe_signature(param, 'param', env, symbol=symbol)
                 param_node += param
-                if multiline:
+                if multi_line:
                     paramlist += param_node
             signode += paramlist
         else:
@@ -4075,7 +4075,7 @@ def describe_signature(self, signode: desc_signature, mode: str,
         assert self.symbol
         # The caller of the domain added a desc_signature node.
         # Always enable multiline:
-        signode['is_multiline'] = True
+        signode['is_multi_line'] = True
         # Put each line in a desc_signature_line node.
         mainDeclNode = addnodes.desc_signature_line()
         mainDeclNode.sphinx_line_type = 'declarator'
@@ -6246,7 +6246,7 @@ def _parse_parameters_and_qualifiers(self, paramMode: str) -> ASTParametersQuali
 
         return ASTParametersQualifiers(
             args, volatile, const, refQual, exceptionSpec, trailingReturn,
-            override, final, attrs, initializer, multiline=self.multiline)
+            override, final, attrs, initializer, multi_line=self.multi_line)
 
     def _parse_decl_specs_simple(self, outer: str, typed: bool) -> ASTDeclSpecsSimple:
         """Just parse the simple ones."""
@@ -7200,7 +7200,7 @@ class CPPObject(ObjectDescription[ASTDeclaration]):
         'noindexentry': directives.flag,
         'nocontentsentry': directives.flag,
         'tparam-line-spec': directives.flag,
-        'singlelinesig': directives.flag,
+        'single-line-signature': directives.flag,
     }
 
     def _add_enumerator_to_parent(self, ast: ASTDeclaration) -> None:
@@ -7358,14 +7358,14 @@ def handle_signature(self, sig: str, signode: desc_signature) -> ASTDeclaration:
         parentSymbol: Symbol = self.env.temp_data['cpp:parent_symbol']
 
         max_len = self.env.config.cpp_maximum_signature_line_length
-        multiline = (
+        multi_line = (
             max_len >= 0
-            and 'singlelinesig' not in self.options
+            and 'single-line-signature' not in self.options
             and len(sig) > max_len
         )
-        signode['is_multiline'] = multiline
+        signode['is_multi_line'] = multi_line
         parser = DefinitionParser(
-            sig, location=signode, config=self.env.config, multiline=multiline
+            sig, location=signode, config=self.env.config, multi_line=multi_line
         )
         try:
             ast = self.parse_definition(parser)

sphinx/domains/python.py

@@ -251,15 +251,15 @@ def _unparse_pep_604_annotation(node: ast.Subscript) -> list[Node]:
 
 
 def _parse_arglist(
-    arglist: str, env: BuildEnvironment | None = None, multiline: bool = False
+    arglist: str, env: BuildEnvironment | None = None, multi_line: bool = False
 ) -> addnodes.desc_parameterlist:
     """Parse a list of arguments using AST parser"""
     params = addnodes.desc_parameterlist()
-    params['is_multiline'] = multiline
+    params['is_multi_line'] = multi_line
     sig = signature_from_str('(%s)' % arglist)
     last_kind = None
     for param in sig.parameters.values():
-        param_node = addnodes.desc_parameterline() if multiline else params
+        param_node = addnodes.desc_parameter_line() if multi_line else params
         if param.kind != param.POSITIONAL_ONLY and last_kind == param.POSITIONAL_ONLY:
             # PEP-570: Separator for Positional Only Parameter: /
             param_node += addnodes.desc_parameter('', '', addnodes.desc_sig_operator('', '/'))
@@ -295,7 +295,7 @@ def _parse_arglist(
                                  support_smartquotes=False)
 
         param_node += node
-        if multiline:
+        if multi_line:
             params += param_node
         last_kind = param.kind
 
@@ -456,7 +456,7 @@ class PyObject(ObjectDescription[Tuple[str, str]]):
         'noindex': directives.flag,
         'noindexentry': directives.flag,
         'nocontentsentry': directives.flag,
-        'singlelinesig': directives.flag,
+        'single-line-signature': directives.flag,
         'module': directives.unchanged,
         'canonical': directives.unchanged,
         'annotation': directives.unchanged,
@@ -539,13 +539,13 @@ def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]
         signode['class'] = classname
         signode['fullname'] = fullname
         max_len = self.env.config.python_maximum_signature_line_length
-        multiline = (
+        multi_line = (
             max_len >= 0
-            and 'singlelinesig' not in self.options
+            and 'single-line-signature' not in self.options
             and len(sig) > max_len
         )
-        signode['is_multiline'] = multiline
-        if multiline:
+        signode['is_multi_line'] = multi_line
+        if multi_line:
             signode['add_permalink'] = True
 
         sig_prefix = self.get_signature_prefix(sig)
@@ -567,7 +567,7 @@ def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]
         signode += addnodes.desc_name(name, name)
         if arglist:
             try:
-                signode += _parse_arglist(arglist, self.env, multiline=multiline)
+                signode += _parse_arglist(arglist, self.env, multi_line=multi_line)
             except SyntaxError:
                 # fallback to parse arglist original parser.
                 # it supports to represent optional arguments (ex. "func(foo [, bar])")

sphinx/util/cfamily.py

@@ -237,11 +237,11 @@ class DefinitionError(Exception):
 class BaseParser:
     def __init__(self, definition: str, *,
                  location: nodes.Node | tuple[str, int] | str,
-                 config: Config, multiline: bool = False) -> None:
+                 config: Config, multi_line: bool = False) -> None:
         self.definition = definition.strip()
         self.location = location  # for warnings
         self.config = config
-        self.multiline = multiline
+        self.multi_line = multi_line
 
         self.pos = 0
         self.end = len(self.definition)

sphinx/writers/_html4.py

@@ -89,7 +89,7 @@ def visit_desc_signature(self, node: Element) -> None:
 
     def depart_desc_signature(self, node: Element) -> None:
         self.protect_literal_text -= 1
-        if not node.get('is_multiline'):
+        if not node.get('is_multi_line'):
             self.add_permalink_ref(node, _('Permalink to this definition'))
         self.body.append('</dt>\n')
 
@@ -151,18 +151,18 @@ def visit_desc_parameterlist(self, node: Element) -> None:
         self.required_params_left = sum([isinstance(c, addnodes.desc_parameter)
                                          for c in node.children])
         self.param_separator = node.child_text_separator
-        if node.get('is_multiline'):
+        if node.get('is_multi_line'):
             self.body.append(self.starttag(node, 'dl'))
 
     def depart_desc_parameterlist(self, node: Element) -> None:
-        if node.get('is_multiline'):
+        if node.get('is_multi_line'):
             self.body.append('</dl>\n\n')
         self.body.append('<span class="sig-paren">)</span>')
 
-    def visit_desc_parameterline(self, node: Element) -> None:
+    def visit_desc_parameter_line(self, node: Element) -> None:
         self.body.append(self.starttag(node, 'dd', ''))
 
-    def depart_desc_parameterline(self, node: Element) -> None:
+    def depart_desc_parameter_line(self, node: Element) -> None:
         self.body.append('</dd>')
 
     # If required parameters are still to come, then put the comma after

sphinx/writers/html5.py

@@ -95,7 +95,7 @@ def visit_desc_signature(self, node: Element) -> None:
 
     def depart_desc_signature(self, node: Element) -> None:
         self.protect_literal_text -= 1
-        if not node.get('is_multiline') or node.get('add_permalink'):
+        if not node.get('is_multi_line') or node.get('add_permalink'):
             self.add_permalink_ref(node, _('Permalink to this definition'))
         self.body.append('</dt>\n')
 
@@ -157,18 +157,18 @@ def visit_desc_parameterlist(self, node: Element) -> None:
         self.required_params_left = sum([isinstance(c, addnodes.desc_parameter)
                                          for c in node.children])
         self.param_separator = node.child_text_separator
-        if node.get('is_multiline'):
+        if node.get('is_multi_line'):
             self.body.append(self.starttag(node, 'dl'))
 
     def depart_desc_parameterlist(self, node: Element) -> None:
-        if node.get('is_multiline'):
+        if node.get('is_multi_line'):
             self.body.append('</dl>\n\n')
         self.body.append('<span class="sig-paren">)</span>')
 
-    def visit_desc_parameterline(self, node: Element) -> None:
+    def visit_desc_parameter_line(self, node: Element) -> None:
         self.body.append(self.starttag(node, 'dd', ''))
 
-    def depart_desc_parameterline(self, node: Element) -> None:
+    def depart_desc_parameter_line(self, node: Element) -> None:
         self.body.append('</dd>')
 
     # If required parameters are still to come, then put the comma after

sphinx/writers/text.py

@@ -599,15 +599,15 @@ def visit_desc_parameterlist(self, node: Element) -> None:
     def depart_desc_parameterlist(self, node: Element) -> None:
         self.add_text(')')
 
-    def visit_desc_parameterline(self, node: Element) -> None:
+    def visit_desc_parameter_line(self, node: Element) -> None:
         self.new_state()
 
-    def depart_desc_parameterline(self, node: Element) -> None:
+    def depart_desc_parameter_line(self, node: Element) -> None:
         self.add_text(',')
         self.end_state(wrap=False, end=None)
 
     def visit_desc_parameter(self, node: Element) -> None:
-        if not self.first_param and not node.parent.parent.get('is_multiline'):
+        if not self.first_param and not node.parent.parent.get('is_multi_line'):
             self.add_text(', ')
         else:
             self.first_param = 0