Merge pull request #7319 from jakobandersen/c_revamp

C domain rewrite

CHANGES

@@ -25,7 +25,7 @@ Incompatible changes
 * Due to the scoping changes for :rst:dir:`productionlist` some uses of
   :rst:role:`token` must be modified to include the scope which was previously
   ignored.
-* #6903: Internal data structure of C, Python, reST and standard domains have
+* #6903: Internal data structure of Python, reST and standard domains have
   changed.  The node_id is added to the index of objects and modules.  Now they
   contains a pair of docname and node_id for cross reference.
 * #7276: C++ domain: Non intended behavior is removed such as ``say_hello_``
@@ -38,6 +38,10 @@ Incompatible changes
   links to ``.. py:function:: say_hello()``
 * #7246: py domain: Drop special cross reference helper for exceptions,
   functions and methods
+* The C domain has been rewritten, with additional directives and roles.
+  The existing ones are now more strict, resulting in new warnings.
+* The attribute ``sphinx_cpp_tagname`` in the ``desc_signature_line`` node
+  has been renamed to ``sphinx_line_type``.
 
 Deprecated
 ----------
@@ -93,6 +97,14 @@ Features added
   ``SearchLanguage.js_splitter_code``
 * #7142: html theme: Add a theme option: ``pygments_dark_style`` to switch the
   style of code-blocks in dark mode
+* The C domain has been rewritten adding for example:
+
+  - Cross-referencing respecting the current scope.
+  - Possible to document anonymous entities.
+  - More specific directives and roles for each type of entitiy,
+    e.g., handling scoping of enumerators.
+  - New role :rst:role:`c:expr` for rendering expressions and types
+    in text.
 
 Bugs fixed
 ----------
@@ -111,6 +123,8 @@ Bugs fixed
   ``html_link_suffix`` in search results
 * #7179: std domain: Fix whitespaces are suppressed on referring GenericObject
 * #7289: console: use bright colors instead of bold
+* #1539: C, parse array types.
+* #2377: C, parse function pointers even in complex types.
 
 Testing
 --------

doc/usage/restructuredtext/domains.rst

@@ -552,47 +552,62 @@ The C Domain
 
 The C domain (name **c**) is suited for documentation of C API.
 
+.. rst:directive:: .. c:member:: declaration
+                   .. c:var:: declaration
+
+   Describes a C struct member or variable. Example signature::
+
+      .. c:member:: PyObject *PyTypeObject.tp_bases
+
+   The difference between the two directives is only cosmetic.
+
 .. rst:directive:: .. c:function:: function prototype
 
    Describes a C function. The signature should be given as in C, e.g.::
 
-      .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
-
-   This is also used to describe function-like preprocessor macros.  The names
-   of the arguments should be given so they may be used in the description.
+      .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
 
    Note that you don't have to backslash-escape asterisks in the signature, as
    it is not parsed by the reST inliner.
 
-.. rst:directive:: .. c:member:: declaration
+.. rst:directive:: .. c:macro:: name
+                   .. c:macro:: name(arg list)
 
-   Describes a C struct member. Example signature::
+   Describes a C macro, i.e., a C-language ``#define``, without the replacement
+   text.
 
-      .. c:member:: PyObject* PyTypeObject.tp_bases
+   .. versionadded:: 3.0
+      The function style variant.
 
-   The text of the description should include the range of values allowed, how
-   the value should be interpreted, and whether the value can be changed.
-   References to structure members in text should use the ``member`` role.
+.. rst:directive:: .. c:struct:: name
 
-.. rst:directive:: .. c:macro:: name
+   Describes a C struct.
+
+   .. versionadded:: 3.0
+
+.. rst:directive:: .. c:union:: name
+
+   Describes a C union.
+
+   .. versionadded:: 3.0
+
+.. rst:directive:: .. c:enum:: name
 
-   Describes a "simple" C macro.  Simple macros are macros which are used for
-   code expansion, but which do not take arguments so cannot be described as
-   functions.  This is a simple C-language ``#define``.  Examples of its use in
-   the Python documentation include :c:macro:`PyObject_HEAD` and
-   :c:macro:`Py_BEGIN_ALLOW_THREADS`.
+   Describes a C enum.
 
-.. rst:directive:: .. c:type:: name
+   .. versionadded:: 3.0
 
-   Describes a C type (whether defined by a typedef or struct). The signature
-   should just be the type name.
+.. rst:directive:: .. c:enumerator:: name
 
-.. rst:directive:: .. c:var:: declaration
+   Describes a C enumerator.
 
-   Describes a global C variable.  The signature should include the type, such
-   as::
+   .. versionadded:: 3.0
 
-      .. c:var:: PyObject* PyClass_Type
+.. rst:directive:: .. c:type:: typedef-like declaration
+                   .. c:type:: name
+
+   Describes a C type, either as a typedef, or the alias for an unspecified
+   type.
 
 .. _c-roles:
 
@@ -602,25 +617,93 @@ Cross-referencing C constructs
 The following roles create cross-references to C-language constructs if they
 are defined in the documentation:
 
-.. rst:role:: c:func
+.. rst:role:: c:member
+              c:data
+              c:var
+              c:func
+              c:macro
+              c:struct
+              c:union
+              c:enum
+              c:enumerator
+              c:type
 
-   Reference a C-language function. Should include trailing parentheses.
+   Reference a C declaration, as defined above.
+   Note that :rst:role:`c:member`, :rst:role:`c:data`, and
+   :rst:role:`c:var` are equivalent.
 
-.. rst:role:: c:member
+   .. versionadded:: 3.0
+      The var, struct, union, enum, and enumerator roles.
 
-   Reference a C-language member of a struct.
 
-.. rst:role:: c:macro
+Anonymous Entities
+~~~~~~~~~~~~~~~~~~
+
+C supports anonymous structs, 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,
+though nested symbols will be found even when omitted.
+The ``@...`` name will always be rendered as **[anonymous]** (possibly as a
+link).
+
+Example::
+
+   .. c:struct:: Data
+
+      .. c:union:: @data
+
+         .. c:var:: int a
+
+         .. c:var:: double b
+
+   Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`.
+
+This will be rendered as:
+
+.. c:struct:: Data
+
+   .. c:union:: @data
+
+      .. c:var:: int a
+
+      .. c:var:: double b
+
+Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`.
+
+.. versionadded:: 3.0
+
+
+Inline Expressions and Types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rst:role:: c:expr
+              c:texpr
+
+   Insert a C expression or type either as inline code (``cpp:expr``)
+   or inline text (``cpp:texpr``). For example::
+
+      .. c:var:: int a = 42
+
+      .. c:function:: int f(int i)
+
+      An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`).
+
+      A type: :c:expr:`const Data*`
+      (or as text :c:texpr:`const Data*`).
+
+   will be rendered as follows:
 
-   Reference a "simple" C macro, as defined above.
+   .. c:var:: int a = 42
 
-.. rst:role:: c:type
+   .. c:function:: int f(int i)
 
-   Reference a C-language type.
+   An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`).
 
-.. rst:role:: c:data
+   A type: :c:expr:`const Data*`
+   (or as text :c:texpr:`const Data*`).
 
-   Reference a C-language variable.
+   .. versionadded:: 3.0
 
 
 .. _cpp-domain:

sphinx/addnodes.py

@@ -119,7 +119,7 @@ class desc_signature_line(nodes.Part, nodes.Inline, nodes.FixedTextElement):
     It should only be used in a ``desc_signature`` with ``is_multiline`` set.
     Set ``add_permalink = True`` for the line that should get the permalink.
     """
-    sphinx_cpp_tagname = ''
+    sphinx_line_type = ''
 
 
 # nodes to use within a desc_signature or desc_signature_line