C++, support constrains in placeholders

3 files changed, 42 insertions, 3 deletions

diff --git a/CHANGES b/CHANGES
index 61d9b4945..432e114a0 100644
--- a/CHANGES
+++ b/CHANGES
@@ -60,7 +60,9 @@ Features added
   - ``constinit`` variables,
   - ``char8_t``,
   - ``explicit(<constant expression>)`` specifier,
-  - digit separators in literals.
+  - digit separators in literals, and
+  - constraints in placeholder type specifiers, aka. adjective syntax
+    (e.g., ``Sortable auto &v``).
 
 * C, add support for digit separators in literals.
 
diff --git a/sphinx/domains/cpp.py b/sphinx/domains/cpp.py
index 854c8f988..c94f1d06d 100644
--- a/sphinx/domains/cpp.py
+++ b/sphinx/domains/cpp.py
@@ -1882,9 +1882,11 @@ class ASTTrailingTypeSpecDecltype(ASTTrailingTypeSpec):
 
 
 class ASTTrailingTypeSpecName(ASTTrailingTypeSpec):
-    def __init__(self, prefix: str, nestedName: ASTNestedName) -> None:
+    def __init__(self, prefix: str, nestedName: ASTNestedName,
+                 placeholderType: Optional[str]) -> None:
         self.prefix = prefix
         self.nestedName = nestedName
+        self.placeholderType = placeholderType
 
     @property
     def name(self) -> ASTNestedName:
@@ -1899,6 +1901,9 @@ class ASTTrailingTypeSpecName(ASTTrailingTypeSpec):
             res.append(self.prefix)
             res.append(' ')
         res.append(transform(self.nestedName))
+        if self.placeholderType is not None:
+            res.append(' ')
+            res.append(self.placeholderType)
         return ''.join(res)
 
     def describe_signature(self, signode: TextElement, mode: str,
@@ -1907,6 +1912,17 @@ class ASTTrailingTypeSpecName(ASTTrailingTypeSpec):
             signode += addnodes.desc_sig_keyword(self.prefix, self.prefix)
             signode += addnodes.desc_sig_space()
         self.nestedName.describe_signature(signode, mode, env, symbol=symbol)
+        if self.placeholderType is not None:
+            signode += addnodes.desc_sig_space()
+            if self.placeholderType == 'auto':
+                signode += addnodes.desc_sig_keyword('auto', 'auto')
+            elif self.placeholderType == 'decltype(auto)':
+                signode += addnodes.desc_sig_keyword('decltype', 'decltype')
+                signode += addnodes.desc_sig_punctuation('(', '(')
+                signode += addnodes.desc_sig_keyword('auto', 'auto')
+                signode += addnodes.desc_sig_punctuation(')', ')')
+            else:
+                assert False, self.placeholderType
 
 
 class ASTFunctionParameter(ASTBase):
@@ -5856,7 +5872,19 @@ class DefinitionParser(BaseParser):
                 prefix = k
                 break
         nestedName = self._parse_nested_name()
-        return ASTTrailingTypeSpecName(prefix, nestedName)
+        self.skip_ws()
+        placeholderType = None
+        if self.skip_word('auto'):
+            placeholderType = 'auto'
+        elif self.skip_word_and_ws('decltype'):
+            if not self.skip_string_and_ws('('):
+                self.fail("Expected '(' after 'decltype' in placeholder type specifier.")
+            if not self.skip_word_and_ws('auto'):
+                self.fail("Expected 'auto' after 'decltype(' in placeholder type specifier.")
+            if not self.skip_string_and_ws(')'):
+                self.fail("Expected ')' after 'decltype(auto' in placeholder type specifier.")
+            placeholderType = 'decltype(auto)'
+        return ASTTrailingTypeSpecName(prefix, nestedName, placeholderType)
 
     def _parse_parameters_and_qualifiers(self, paramMode: str) -> ASTParametersQualifiers:
         if paramMode == 'new':
diff --git a/tests/test_domain_cpp.py b/tests/test_domain_cpp.py
index cf2774af4..1ad216e5a 100644
--- a/tests/test_domain_cpp.py
+++ b/tests/test_domain_cpp.py
@@ -866,6 +866,15 @@ def test_domain_cpp_ast_templates():
     check('type', 'template<C T = int&> {key}A', {2: 'I_1CE1A'}, key='using')
 
 
+def test_domain_cpp_ast_placeholder_types():
+    check('function', 'void f(Sortable auto &v)', {1: 'f__SortableR', 2: '1fR8Sortable'})
+    check('function', 'void f(const Sortable auto &v)', {1: 'f__SortableCR', 2: '1fRK8Sortable'})
+    check('function', 'void f(Sortable decltype(auto) &v)', {1: 'f__SortableR', 2: '1fR8Sortable'})
+    check('function', 'void f(const Sortable decltype(auto) &v)', {1: 'f__SortableCR', 2: '1fRK8Sortable'})
+    check('function', 'void f(Sortable decltype ( auto ) &v)', {1: 'f__SortableR', 2: '1fR8Sortable'},
+          output='void f(Sortable decltype(auto) &v)')
+
+
 def test_domain_cpp_ast_requires_clauses():
     check('function', 'template<typename T> requires A auto f() -> void requires B',
           {4: 'I0EIQaa1A1BE1fvv'})