C, initial introduction of tags

jakobandersen · jakobandersen · commit 143f84263fd5 · 2021-01-09T17:03:15.000+01:00
diff --git a/sphinx/domains/c.py b/sphinx/domains/c.py
@@ -9,8 +9,8 @@
 """
 
 import re
-from typing import (Any, Callable, Dict, Generator, Iterator, List, Tuple, Type, TypeVar,
-                    Union, cast)
+from typing import (Any, Callable, Dict, Generator, Iterator, List, Optional, Tuple, Type,
+                    TypeVar, Union, cast)
 
 from docutils import nodes
 from docutils.nodes import Element, Node, TextElement, system_message
@@ -78,8 +78,8 @@
 _expression_assignment_ops = ["=", "*=", "/=", "%=", "+=", "-=",
                               ">>=", "<<=", "&=", "and_eq", "^=", "xor_eq", "|=", "or_eq"]
 
-_max_id = 1
-_id_prefix = [None, 'c.', 'Cv2.']
+_max_id = 2
+_id_prefix = [None, 'c.', 'C2-']
 # Ids are used in lookup keys which are used across pickled files,
 # so when _max_id changes, make sure to update the ENV_VERSION.
 
@@ -108,31 +108,54 @@ def describe_signature(self, signode: TextElement, mode: str,
 ################################################################################
 
 class ASTIdentifier(ASTBaseBase):
-    def __init__(self, identifier: str) -> None:
+    def __init__(self, identifier: str, tag: Optional[str]) -> None:
+        # tag:
+        # - len > 0: it's a struct/union/enum
+        # - len == 0: it's not a struct/union/enum
+        # - None: for matching, can be either
         assert identifier is not None
         assert len(identifier) != 0
         self.identifier = identifier
+        self.tag = tag
 
     def __eq__(self, other: Any) -> bool:
-        return type(other) is ASTIdentifier and self.identifier == other.identifier
+        return type(other) is ASTIdentifier \
+            and self.identifier == other.identifier \
+            and self.tag == other.tag
 
     def is_anon(self) -> bool:
         return self.identifier[0] == '@'
 
+    def get_id(self, version: int) -> str:
+        if version <= 1:
+            return self.identifier
+        if self.tag:
+            assert len(self.tag) != 0
+            return '-' + self.identifier
+        else:
+            return self.identifier
+
     # and this is where we finally make a difference between __str__ and the display string
 
     def __str__(self) -> str:
-        return self.identifier
+        return self.tag + " " + self.identifier if self.tag else self.identifier
 
     def get_display_string(self) -> str:
-        return "[anonymous]" if self.is_anon() else self.identifier
+        id = "[anonymous]" if self.is_anon() else self.identifier
+        return self.tag + " " + id if self.tag else id
 
     def describe_signature(self, signode: TextElement, mode: str, env: "BuildEnvironment",
                            prefix: str, symbol: "Symbol") -> None:
         # note: slightly different signature of describe_signature due to the prefix
         verify_description_mode(mode)
+        if self.tag:
+            signode += nodes.Text(self.tag)
+            signode += nodes.Text(' ')
         if mode == 'markType':
-            targetText = prefix + self.identifier
+            if self.tag:
+                targetText = prefix + self.tag + ' ' + self.identifier
+            else:
+                targetText = prefix + self.identifier
             pnode = addnodes.pending_xref('', refdomain='c',
                                           reftype='identifier',
                                           reftarget=targetText, modname=None,
@@ -164,12 +187,17 @@ def __init__(self, names: List[ASTIdentifier], rooted: bool) -> None:
         self.names = names
         self.rooted = rooted
 
+    def setTagsToPattern(self) -> None:
+        for n in self.names:
+            if n.tag == '':
+                n.tag = None
+
     @property
     def name(self) -> "ASTNestedName":
         return self
 
     def get_id(self, version: int) -> str:
-        return '.'.join(str(n) for n in self.names)
+        return '.'.join(n.get_id(version) for n in self.names)
 
     def _stringify(self, transform: StringifyTransform) -> str:
         res = '.'.join(transform(n) for n in self.names)
@@ -595,27 +623,18 @@ def describe_signature(self, signode: TextElement, mode: str,
 
 
 class ASTTrailingTypeSpecName(ASTTrailingTypeSpec):
-    def __init__(self, prefix: str, nestedName: ASTNestedName) -> None:
-        self.prefix = prefix
+    def __init__(self, nestedName: ASTNestedName) -> None:
         self.nestedName = nestedName
 
     @property
     def name(self) -> ASTNestedName:
         return self.nestedName
 
     def _stringify(self, transform: StringifyTransform) -> str:
-        res = []
-        if self.prefix:
-            res.append(self.prefix)
-            res.append(' ')
-        res.append(transform(self.nestedName))
-        return ''.join(res)
+        return transform(self.nestedName)
 
     def describe_signature(self, signode: TextElement, mode: str,
                            env: "BuildEnvironment", symbol: "Symbol") -> None:
-        if self.prefix:
-            signode += addnodes.desc_annotation(self.prefix, self.prefix)
-            signode += nodes.Text(' ')
         self.nestedName.describe_signature(signode, mode, env, symbol=symbol)
 
 
@@ -1863,23 +1882,9 @@ def handleDuplicateDeclaration(symbol: "Symbol", candSymbol: "Symbol") -> None:
                 candSymbol.isRedeclaration = True
                 raise _DuplicateSymbolError(symbol, declaration)
 
-            if declaration.objectType != "function":
-                assert len(withDecl) <= 1
-                handleDuplicateDeclaration(withDecl[0], candSymbol)
-                # (not reachable)
-
-            # a function, so compare IDs
-            candId = declaration.get_newest_id()
-            if Symbol.debug_lookup:
-                Symbol.debug_print("candId:", candId)
-            for symbol in withDecl:
-                oldId = symbol.declaration.get_newest_id()
-                if Symbol.debug_lookup:
-                    Symbol.debug_print("oldId: ", oldId)
-                if candId == oldId:
-                    handleDuplicateDeclaration(symbol, candSymbol)
-                    # (not reachable)
-            # no candidate symbol found with matching ID
+            assert len(withDecl) <= 1
+            handleDuplicateDeclaration(withDecl[0], candSymbol)
+            # (not reachable)
         # if there is an empty symbol, fill that one
         if len(noDecl) == 0:
             if Symbol.debug_lookup:
@@ -1961,8 +1966,12 @@ def add_declaration(self, declaration: ASTDeclaration,
             Symbol.debug_print("add_declaration:")
         assert declaration is not None
         assert docname is not None
-        assert line is not None
-        nestedName = declaration.name
+        assert declaration.name.names[-1].tag == ''
+        if declaration.objectType in ('struct', 'union', 'enum'):
+            nestedName = declaration.name.clone()
+            nestedName.names[-1].tag = declaration.objectType
+        else:
+            nestedName = declaration.name
         res = self._add_symbols(nestedName, declaration, docname, line)
         if Symbol.debug_lookup:
             Symbol.debug_indent -= 1
@@ -2090,8 +2099,6 @@ class DefinitionParser(BaseParser):
         '__int64',
     )
 
-    _prefix_keys = ('struct', 'enum', 'union')
-
     @property
     def language(self) -> str:
         return 'C'
@@ -2183,10 +2190,9 @@ def _parse_primary_expression(self) -> ASTExpression:
         res = self._parse_paren_expression()
         if res is not None:
             return res
-        nn = self._parse_nested_name()
-        if nn is not None:
-            return ASTIdExpression(nn)
-        return None
+        nn = self._parse_nested_name(allowTags=None)
+        assert nn is not None
+        return ASTIdExpression(nn)
 
     def _parse_initializer_list(self, name: str, open: str, close: str
                                 ) -> Tuple[List[ASTExpression], bool]:
@@ -2267,7 +2273,7 @@ def _parse_postfix_expression(self) -> ASTPostfixExpr:
                     # don't steal the arrow
                     self.pos -= 3
                 else:
-                    name = self._parse_nested_name()
+                    name = self._parse_nested_name(allowTags=None)
                     postFixes.append(ASTPostfixMemberOfPointer(name))
                     continue
             if self.skip_string('++'):
@@ -2485,29 +2491,46 @@ def _parse_expression_fallback(
             value = self.definition[startPos:self.pos].strip()
         return ASTFallbackExpr(value.strip())
 
-    def _parse_nested_name(self) -> ASTNestedName:
-        names = []  # type: List[Any]
+    def _parse_nested_name(self, *, allowTags: Optional[str] = 'not last') -> ASTNestedName:
+        # A dot-separated list of identifiers, each with an optional struct/union/enum tag.
+        # A leading dot makes the name rooted at global scope.
+
+        assert allowTags in (None, 'all', 'not last')
+
+        names = []  # type: List[ASTIdentifier]
 
-        self.skip_ws()
         rooted = False
         if self.skip_string('.'):
             rooted = True
         while 1:
             self.skip_ws()
+            tag = ''
+            if allowTags is not None:
+                for k in ('struct', 'union', 'enum'):
+                    if self.skip_word_and_ws(k):
+                        tag = k
+                        break
+            afterTagPos = self.pos
             if not self.match(identifier_re):
                 self.fail("Expected identifier in nested name.")
             identifier = self.matched_text
             # make sure there isn't a keyword
             if identifier in _keywords:
                 self.fail("Expected identifier in nested name, "
                           "got keyword: %s" % identifier)
-            ident = ASTIdentifier(identifier)
+            ident = ASTIdentifier(identifier, tag)
             names.append(ident)
 
             self.skip_ws()
             if not self.skip_string('.'):
                 break
-        return ASTNestedName(names, rooted)
+
+        # post hax to explicitly forbid the last one to have a tag
+        if allowTags == 'not last' and names[-1].tag != '':
+            self.pos = afterTagPos
+            self.fail("Expected identifier in nested name, "
+                      "got keyword: %s" % names[-1].tag)
+        return ASTNestedName(names, rooted=rooted)
 
     def _parse_trailing_type_spec(self) -> ASTTrailingTypeSpec:
         # fundamental types
@@ -2540,16 +2563,8 @@ def _parse_trailing_type_spec(self) -> ASTTrailingTypeSpec:
         if len(elements) > 0:
             return ASTTrailingTypeSpecFundamental(' '.join(elements))
 
-        # prefixed
-        prefix = None
-        self.skip_ws()
-        for k in self._prefix_keys:
-            if self.skip_word_and_ws(k):
-                prefix = k
-                break
-
-        nestedName = self._parse_nested_name()
-        return ASTTrailingTypeSpecName(prefix, nestedName)
+        nestedName = self._parse_nested_name(allowTags='all')
+        return ASTTrailingTypeSpecName(nestedName)
 
     def _parse_parameters(self, paramMode: str) -> ASTParameters:
         self.skip_ws()
@@ -2677,7 +2692,7 @@ def _parse_declarator_name_suffix(
                 if self.matched_text in _keywords:
                     self.fail("Expected identifier, "
                               "got keyword: %s" % self.matched_text)
-                identifier = ASTIdentifier(self.matched_text)
+                identifier = ASTIdentifier(self.matched_text, '')
                 declId = ASTNestedName([identifier], rooted=False)
             else:
                 declId = None
@@ -2939,7 +2954,7 @@ def _parse_macro(self) -> ASTMacro:
                 break
             if not self.match(identifier_re):
                 self.fail("Expected identifier in macro parameters.")
-            nn = ASTNestedName([ASTIdentifier(self.matched_text)], rooted=False)
+            nn = ASTNestedName([ASTIdentifier(self.matched_text, '')], rooted=False)
             # Allow named variadic args:
             # https://gcc.gnu.org/onlinedocs/cpp/Variadic-Macros.html
             self.skip_ws()
@@ -3036,10 +3051,10 @@ def parse_declaration(self, objectType: str, directiveType: str) -> ASTDeclarati
         return ASTDeclaration(objectType, directiveType, declaration, semicolon)
 
     def parse_namespace_object(self) -> ASTNestedName:
-        return self._parse_nested_name()
+        return self._parse_nested_name(allowTags='all')
 
     def parse_xref_object(self) -> ASTNestedName:
-        name = self._parse_nested_name()
+        name = self._parse_nested_name(allowTags='all')
         # if there are '()' left, just skip them
         self.skip_ws()
         self.skip_string('()')
@@ -3069,7 +3084,7 @@ def parse_expression(self) -> Union[ASTExpression, ASTType]:
 
 
 def _make_phony_error_name() -> ASTNestedName:
-    return ASTNestedName([ASTIdentifier("PhonyNameDueToError")], rooted=False)
+    return ASTNestedName([ASTIdentifier("PhonyNameDueToError", None)], rooted=False)
 
 
 class CObject(ObjectDescription[ASTDeclaration]):
@@ -3800,9 +3815,18 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value("c_allow_pre_v3", False, 'env')
     app.add_config_value("c_warn_on_allowed_pre_v3", True, 'env')
 
+    # debug stuff
+    app.add_config_value("c_debug_lookup", False, '')
+    app.add_config_value("c_debug_show_tree", False, '')
+
+    def setDebugFlags(app):
+        Symbol.debug_lookup = app.config.c_debug_lookup
+        Symbol.debug_show_tree = app.config.c_debug_show_tree
+    app.connect("builder-inited", setDebugFlags)
+
     return {
         'version': 'builtin',
-        'env_version': 2,
+        'env_version': 3,
         'parallel_read_safe': True,
         'parallel_write_safe': True,
     }
diff --git a/tests/roots/test-domain-c/ids-vs-tags.rst b/tests/roots/test-domain-c/ids-vs-tags.rst
@@ -0,0 +1,10 @@
+.. c:struct:: f_struct
+.. c:type:: struct f_struct f_struct
+.. c:union:: f_union
+.. c:type:: struct f_union f_union
+.. c:enum:: f_enum
+.. c:type:: struct f_enum f_enum
+
+- :c:struct:`f_struct`, :c:type:`f_struct`
+- :c:union:`f_union`, :c:type:`f_union`
+- :c:enum:`f_enum`, :c:type:`f_enum`
diff --git a/tests/test_build_html.py b/tests/test_build_html.py
@@ -289,11 +289,11 @@ def test_html4_output(app, status, warning):
         (".//a[@class='reference internal'][@href='#errmod.Error']/strong", 'Error'),
         # C references
         (".//span[@class='pre']", 'CFunction()'),
-        (".//a[@href='#c.Sphinx_DoSomething']", ''),
-        (".//a[@href='#c.SphinxStruct.member']", ''),
-        (".//a[@href='#c.SPHINX_USE_PYTHON']", ''),
-        (".//a[@href='#c.SphinxType']", ''),
-        (".//a[@href='#c.sphinx_global']", ''),
+        (".//a[@href='#C2-Sphinx_DoSomething']", ''),
+        (".//a[@href='#C2-SphinxStruct.member']", ''),
+        (".//a[@href='#C2-SPHINX_USE_PYTHON']", ''),
+        (".//a[@href='#C2-SphinxType']", ''),
+        (".//a[@href='#C2-sphinx_global']", ''),
         # test global TOC created by toctree()
         (".//ul[@class='current']/li[@class='toctree-l1 current']/a[@href='#']",
          'Testing object descriptions'),
diff --git a/tests/test_domain_c.py b/tests/test_domain_c.py
