C言語ドメイン¶

Added in version 1.0.

C言語ドメイン(c)は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:: function prototype¶

Cの関数の説明に使用します。シグニチャはC言語内で書かれる様に記述します。例えば以下のように書きます:

.. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

シグネチャ内のアスタリスクはバックスラッシュでエスケープする必要はありません。この中はreSTの行内のテキスト処理のパーサは実行されず、専用のパーサで処理されます。

In the description of a function you can use the following info fields (see also 詳細情報フィールドのリスト).

param, parameter, arg, argument, Description of a parameter.
type: Type of a parameter, written as if passed to the c:expr role.
returns, return: 返り値の値について説明をします
rtype: Return type, written as if passed to the c:expr role.
retval, retvals: An alternative to returns for describing the result of the function.

Added in version 4.3: The retval field type.

例えば:

.. 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_t nitems)¶

No-contents-entry:

No-index-entry:

パラメータ:

type -- description of the first parameter.
nitems -- description of the second parameter.

戻り値:

a result.

戻り値:

NULL -- under some conditions.
NULL -- under some other conditions as well.

:single-line-parameter-list: (no value)¶: Ensures that the function's parameters will be emitted on a single logical line, overriding c_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.

.. 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 c:function directive.

Added in version 3.0: The function style variant.

:single-line-parameter-list: (no value)¶: Ensures that the macro's parameters will be emitted on a single logical line, overriding c_maximum_signature_line_length and maximum_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-like declaration¶
.. c:type:: name: Describes a C type, either as a typedef, or the alias for an unspecified type.

C言語の要素へのクロスリファレンス¶

以下のロールは、もしドキュメントの中に定義の説明があれば、C言語の要素へのクロスリファレンスを作成します:

: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 c:member, c:data, and c: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 a link).

サンプル:

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

struct Data¶

union [anonymous]¶

int a¶

double b¶

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 main documentation, 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 specified as they can in the c:any role.

例えば:

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

.. c:alias:: data
             f

becomes

int data¶

int f(double k)¶

int data
int f(double k)

Added in version 3.2.

オプション

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

int a = 42¶

int f(int i)¶

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

A type: const Data* (or as text const Data*).

Added in version 3.0.

名前空間¶

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

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

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

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

設定値¶

See Options for the C domain.

Sphinx

On this page

Site navigation