summaryrefslogtreecommitdiffstats
path: root/doc/usage/domains/c.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-06-05 16:20:58 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-06-05 16:20:58 +0000
commitffcb4b87846b4e4a2d9eee8df4b7ec40365878b8 (patch)
tree3c64877dd20ad1141111c77b3463e95686002b39 /doc/usage/domains/c.rst
parentAdding debian version 7.2.6-8. (diff)
downloadsphinx-ffcb4b87846b4e4a2d9eee8df4b7ec40365878b8.tar.xz
sphinx-ffcb4b87846b4e4a2d9eee8df4b7ec40365878b8.zip
Merging upstream version 7.3.7.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/usage/domains/c.rst')
-rw-r--r--doc/usage/domains/c.rst367
1 files changed, 367 insertions, 0 deletions
diff --git a/doc/usage/domains/c.rst b/doc/usage/domains/c.rst
new file mode 100644
index 0000000..3c1a41d
--- /dev/null
+++ b/doc/usage/domains/c.rst
@@ -0,0 +1,367 @@
+.. highlight:: rst
+
+============
+The C Domain
+============
+
+.. versionadded:: 1.0
+
+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)
+
+ Note that you don't have to backslash-escape asterisks in the signature, as
+ it is not parsed by the reST inliner.
+
+ In the description of a function you can use the following info fields
+ (see also :ref:`info-field-lists`).
+
+ * ``param``, ``parameter``, ``arg``, ``argument``,
+ Description of a parameter.
+ * ``type``: Type of a parameter,
+ written as if passed to the :rst:role:`c:expr` role.
+ * ``returns``, ``return``: Description of the return value.
+ * ``rtype``: Return type,
+ written as if passed to the :rst:role:`c:expr` role.
+ * ``retval``, ``retvals``: An alternative to ``returns`` for describing
+ the result of the function.
+
+ .. versionadded:: 4.3
+ The ``retval`` field type.
+
+ For example::
+
+ .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+ :param type: description of the first parameter.
+ :param nitems: description of the second parameter.
+ :returns: a result.
+ :retval NULL: under some conditions.
+ :retval NULL: under some other conditions as well.
+
+ which renders as
+
+ .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+ ..
+ ** for some editors (e.g., vim) to stop bold-highlighting the source
+
+ :no-contents-entry:
+ :no-index-entry:
+ :param type: description of the first parameter.
+ :param nitems: description of the second parameter.
+ :returns: a result.
+ :retval NULL: under some conditions.
+ :retval NULL: under some other conditions as well.
+
+ .. rst:directive:option:: single-line-parameter-list
+ :type: no value
+
+ Ensures that the function's parameters will be emitted on a single logical
+ line, overriding :confval:`c_maximum_signature_line_length` and
+ :confval:`maximum_signature_line_length`.
+
+ .. versionadded:: 7.1
+
+
+.. rst:directive:: .. c:macro:: name
+ .. c:macro:: name(arg list)
+
+ Describes a C macro, i.e., a C-language ``#define``, without the replacement
+ text.
+
+ In the description of a macro you can use the same info fields as for the
+ :rst:dir:`c:function` directive.
+
+ .. versionadded:: 3.0
+ The function style variant.
+
+ .. rst:directive:option:: single-line-parameter-list
+ :type: no value
+
+ Ensures that the macro's parameters will be emitted on a single logical
+ line, overriding :confval:`c_maximum_signature_line_length` and
+ :confval:`maximum_signature_line_length`.
+
+ .. versionadded:: 7.1
+
+.. rst:directive:: .. c:struct:: 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 C enum.
+
+ .. versionadded:: 3.0
+
+.. rst:directive:: .. c:enumerator:: name
+
+ Describes a C enumerator.
+
+ .. versionadded:: 3.0
+
+.. 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:
+
+Cross-referencing C constructs
+------------------------------
+
+The following roles create cross-references to C-language constructs if they
+are defined in the documentation:
+
+.. 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 declaration, as defined above.
+ Note that :rst:role:`c:member`, :rst:role:`c:data`, and
+ :rst:role:`c:var` are equivalent.
+
+ .. versionadded:: 3.0
+ The var, struct, union, enum, and enumerator roles.
+
+
+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
+ :no-contents-entry:
+ :no-index-entry:
+
+ .. c:union:: @data
+ :no-contents-entry:
+ :no-index-entry:
+
+ .. c:var:: int a
+ :no-contents-entry:
+ :no-index-entry:
+
+ .. c:var:: double b
+ :no-contents-entry:
+ :no-index-entry:
+
+Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`.
+
+.. versionadded:: 3.0
+
+
+Aliasing Declarations
+---------------------
+
+.. c:namespace-push:: @alias
+
+Sometimes it may be helpful list declarations elsewhere than their main
+documentation, e.g., when creating a synopsis of an interface.
+The following directive can be used for this purpose.
+
+.. rst:directive:: .. c:alias:: name
+
+ Insert one or more alias declarations. Each entity can be specified
+ as they can in the :rst:role:`c:any` role.
+
+ For example::
+
+ .. c:var:: int data
+ .. c:function:: int f(double k)
+
+ .. c:alias:: data
+ f
+
+ becomes
+
+ .. c:var:: int data
+ :no-contents-entry:
+ :no-index-entry:
+
+ .. c:function:: int f(double k)
+ :no-contents-entry:
+ :no-index-entry:
+
+ .. c:alias:: data
+ f
+
+ .. versionadded:: 3.2
+
+
+ .. rubric:: Options
+
+ .. rst:directive:option:: maxdepth: int
+
+ Insert nested declarations as well, up to the total depth given.
+ Use 0 for infinite depth and 1 for just the mentioned declaration.
+ Defaults to 1.
+
+ .. versionadded:: 3.3
+
+ .. rst:directive:option:: noroot
+
+ Skip the mentioned declarations and only render nested declarations.
+ Requires ``maxdepth`` either 0 or at least 2.
+
+ .. versionadded:: 3.5
+
+
+.. c:namespace-pop::
+
+
+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:
+
+ .. c:var:: int a = 42
+ :no-contents-entry:
+ :no-index-entry:
+
+ .. c:function:: int f(int i)
+ :no-contents-entry:
+ :no-index-entry:
+
+ 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*`).
+
+ .. versionadded:: 3.0
+
+
+Namespacing
+-----------
+
+.. versionadded:: 3.1
+
+The C language it self does not support namespacing, but it can sometimes be
+useful to emulate it in documentation, e.g., to show alternate declarations.
+The feature may also be used to document members of structs/unions/enums
+separate from their parent declaration.
+
+The current scope can be changed using three namespace directives. They manage
+a stack declarations where ``c:namespace`` resets the stack and changes a given
+scope.
+
+The ``c:namespace-push`` directive changes the scope to a given inner scope
+of the current one.
+
+The ``c:namespace-pop`` directive undoes the most recent
+``c:namespace-push`` directive.
+
+.. rst:directive:: .. c:namespace:: scope specification
+
+ Changes the current scope for the subsequent objects to the given scope, and
+ resets the namespace directive stack. Note that nested scopes can be
+ specified by separating with a dot, e.g.::
+
+ .. c:namespace:: Namespace1.Namespace2.SomeStruct.AnInnerStruct
+
+ All subsequent objects will be defined as if their name were declared with
+ the scope prepended. The subsequent cross-references will be searched for
+ starting in the current scope.
+
+ Using ``NULL`` or ``0`` as the scope will change to global scope.
+
+.. rst:directive:: .. c:namespace-push:: scope specification
+
+ Change the scope relatively to the current scope. For example, after::
+
+ .. c:namespace:: A.B
+
+ .. c:namespace-push:: C.D
+
+ the current scope will be ``A.B.C.D``.
+
+.. rst:directive:: .. c:namespace-pop::
+
+ Undo the previous ``c:namespace-push`` directive (*not* just pop a scope).
+ For example, after::
+
+ .. c:namespace:: A.B
+
+ .. c:namespace-push:: C.D
+
+ .. c:namespace-pop::
+
+ the current scope will be ``A.B`` (*not* ``A.B.C``).
+
+ If no previous ``c:namespace-push`` directive has been used, but only a
+ ``c:namespace`` directive, then the current scope will be reset to global
+ scope. That is, ``.. c:namespace:: A.B`` is equivalent to::
+
+ .. c:namespace:: NULL
+
+ .. c:namespace-push:: A.B
+
+Configuration Variables
+-----------------------
+
+See :ref:`c-config`.