The C Domain

Added in version 1.0.

The C domain (namec) is suited for documentation of C API.

..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.

..c:function::functionprototype

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, asit is not parsed by the reStructuredText inliner.

In the description of a function you can use the following info fields(see alsoInfo field lists).

  • param,parameter,arg,argument,Description of a parameter.

  • type: Type of a parameter,written as if passed to thec:expr role.

  • returns,return: Description of the return value.

  • rtype: Return type,written as if passed to thec:expr role.

  • retval,retvals: An alternative toreturns for describingthe result of the function.

Added in version 4.3:Theretval 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

PyObject*PyType_GenericAlloc(PyTypeObject*type,Py_ssize_tnitems)
No-contents-entry:

No-index-entry:

Parameters:

  • type – description of the first parameter.

  • nitems – description of the second parameter.

Returns:

a result.

Return values:

  • NULL – under some conditions.

  • NULL – under some other conditions as well.

:single-line-parameter-list:(novalue)

Ensures that the function’s parameters will be emitted on a single logicalline, overridingc_maximum_signature_line_length andmaximum_signature_line_length.

Added in version 7.1.

..c:macro::name
..c:macro::name(arglist)

Describes a C macro, i.e., a C-language#define, without the replacementtext.

In the description of a macro you can use the same info fields as for thec:function directive.

Added in version 3.0:The function style variant.

:single-line-parameter-list:(novalue)

Ensures that the macro’s parameters will be emitted on a single logicalline, overridingc_maximum_signature_line_length andmaximum_signature_line_length.

Added in version 7.1.

..c:struct::name

Describes a C struct.

Added in version 3.0.

..c:union::name

Describes a C union.

Added in version 3.0.

..c:enum::name

Describes a C enum.

Added in version 3.0.

..c:enumerator::name

Describes a C enumerator.

Added in version 3.0.

..c:type::typedef-likedeclaration
..c:type::name

Describes a C type, either as a typedef, or the alias for an unspecifiedtype.

Cross-referencing C constructs

The following roles create cross-references to C-language constructs if theyare defined in the documentation:

: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 thatc:member,c:data, andc:var are equivalent.

Added in version 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 alink).

Example:

..c:struct:: Data   ..c:union:: @data      ..c:var:: int a      ..c:var:: double bExplicit ref::c:var:`[email protected]`. Short-hand ref::c:var:`Data.a`.

This will be rendered as:

structData
union[anonymous]
inta
doubleb

Explicit ref:Data.[anonymous].a. Short-hand ref:Data.a.

Added in version 3.0.

Aliasing Declarations

Sometimes it may be helpful list declarations elsewhere than their maindocumentation, e.g., when creating a synopsis of an interface.The following directive can be used for this purpose.

..c:alias::name

Insert one or more alias declarations. Each entity can be specifiedas they can in thec:any role.

For example:

..c:var:: int data..c:function:: int f(double k)..c:alias:: data             f

becomes

intdata
intf(doublek)
intdata
intf(doublek)

Added in version 3.2.

Options

: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.

Added in version 3.3.

:noroot:

Skip the mentioned declarations and only render nested declarations.Requiresmaxdepth either 0 or at least 2.

Added in version 3.5.

Inline Expressions and Types

: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:

inta=42
intf(inti)

An expression:a*f(a) (or as text:a*f(a)).

A type:constData*(or as textconstData*).

Added in version 3.0.

Namespacing

Added in version 3.1.

The C language it self does not support namespacing, but it can sometimes beuseful to emulate it in documentation, e.g., to show alternate declarations.The feature may also be used to document members of structs/unions/enumsseparate from their parent declaration.

The current scope can be changed using three namespace directives. They managea stack declarations wherec:namespace resets the stack and changes a givenscope.

Thec:namespace-push directive changes the scope to a given inner scopeof the current one.

Thec:namespace-pop directive undoes the most recentc:namespace-push directive.

..c:namespace::scopespecification

Changes the current scope for the subsequent objects to the given scope, andresets the namespace directive stack. Note that nested scopes can bespecified 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 withthe scope prepended. The subsequent cross-references will be searched forstarting in the current scope.

UsingNULL or0 as the scope will change to global scope.

..c:namespace-push::scopespecification

Change the scope relatively to the current scope. For example, after:

..c:namespace:: A.B..c:namespace-push:: C.D

the current scope will beA.B.C.D.

..c:namespace-pop::

Undo the previousc: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 beA.B (notA.B.C).

If no previousc:namespace-push directive has been used, but only ac:namespace directive, then the current scope will be reset to globalscope. That is,..c:namespace::A.B is equivalent to:

..c:namespace:: NULL..c:namespace-push:: A.B

Configuration Variables

SeeOptions for the C domain.

Previous
The Standard Domain
Next
The C++ Domain