C++, add support for anon entities.

Anonymous entities are specified with names starting with "@",
but are rendered as "[anonymous]".

Fixes sphinx-doc/sphinx#3593 and sphinx-doc/sphinx#2683.

CHANGES

@@ -129,6 +129,8 @@ Features added
   option of highlight directive
 * C++, add a ``cpp:texpr`` role as a sibling to ``cpp:expr``.
 * C++, add support for unions.
+* C++, add support for anonymous entities using names staring with ``@``.
+  Fixes #3593 and #2683.
 * #3606: MathJax should be loaded with async attribute
 * html: Output ``canonical_url`` metadata if :confval:`html_baseurl` set (refs:
   #4193)

doc/usage/restructuredtext/domains.rst

@@ -759,6 +759,41 @@ Some directives support options:
 - ``:tparam-line-spec:``, for templated declarations.
   If specified, each template parameter will be rendered on a separate line.
 
+Anonymous Entities
+~~~~~~~~~~~~~~~~~~
+
+C++ supposrts anonymous namespaces, classes, enums, and unions.
+For the sake of documentation they must be given some name that starts with ``@``,
+e.g., ``@42`` or ``@data``.
+These names can also be used in cross-references and (type) expressions,
+though nested symbols will be found even when omitted.
+The ``@...`` name will always be rendered as **[anonymous]** (possibly as a link).
+
+Example::
+
+   .. cpp:class:: Data
+
+      .. cpp:union:: @data
+
+         .. cpp:var:: int a
+
+         .. cpp:var:: double b
+
+   Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
+
+This will be rendered as:
+
+.. cpp:class:: Data
+
+   .. cpp:union:: @data
+
+      .. cpp:var:: int a
+
+      .. cpp:var:: double b
+
+Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
+
+
 Constrained Templates
 ~~~~~~~~~~~~~~~~~~~~~
 

tests/test_domain_cpp.py

@@ -414,7 +414,7 @@ def test_function_definitions():
     # TODO: make tests for functions in a template, e.g., Test<int&&()>
     # such that the id generation for function type types is correct.
 
-    check('function', 'friend std::ostream &f(std::ostream&, int)',
+    check('function', 'friend std::ostream &f(std::ostream &s, int i)',
           {1: 'f__osR.i', 2: '1fRNSt7ostreamEi'})
 
     # from breathe#223
@@ -509,6 +509,13 @@ def test_enum_definitions():
     check('enumerator', 'A = std::numeric_limits<unsigned long>::max()', {2: "1A"})
 
 
+def test_anon_definitions():
+    check('class', '@a', {3: "Ut1_a"})
+    check('union', '@a', {3: "Ut1_a"})
+    check('enum', '@a', {3: "Ut1_a"})
+    check('class', '@1', {3: "Ut1_1"})
+
+
 def test_templates():
     check('class', "A<T>", {2: "IE1AI1TE"}, output="template<> A<T>")
     # first just check which objects support templating