C, initial rewrite

doc/usage/restructuredtext/domains.rst

@@ -556,43 +556,29 @@ The C domain (name **c**) is suited for documentation of C API.
 
    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
+                   .. c:var:: declaration
 
-   Describes a C struct member. Example signature::
+   Describes a C struct member or variable. Example signature::
 
-      .. c:member:: PyObject* PyTypeObject.tp_bases
-
-   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.
+      .. c:member:: PyObject *PyTypeObject.tp_bases
 
 .. rst:directive:: .. c:macro:: name
+                   .. c:macro:: name(arg list)
 
-   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 macro, i.e., a C-language ``#define``, without the replacement
+   text.
 
-.. rst:directive:: .. c:type:: name
+.. rst:directive:: .. c:type:: typedef-like declaration
+                   .. c:type:: name
 
-   Describes a C type (whether defined by a typedef or struct). The signature
-   should just be the type name.
-
-.. rst:directive:: .. c:var:: declaration
-
-   Describes a global C variable.  The signature should include the type, such
-   as::
-
-      .. c:var:: PyObject* PyClass_Type
+   Describes a C type, either as a typedef, or the alias for an unspecified
+   type.
 
 .. _c-roles:
 
@@ -607,21 +593,18 @@ are defined in the documentation:
    Reference a C-language function. Should include trailing parentheses.
 
 .. rst:role:: c:member
+              c:data
 
-   Reference a C-language member of a struct.
+   Reference a C-language member of a struct or variable.
 
 .. rst:role:: c:macro
 
-   Reference a "simple" C macro, as defined above.
+   Reference a simple C macro, as defined above.
 
 .. rst:role:: c:type
 
    Reference a C-language type.
 
-.. rst:role:: c:data
-
-   Reference a C-language variable.
-
 
 .. _cpp-domain: