O domínio C¶

Adicionado na versão 1.0.

O domínio C (nome c) é adequado para documentação de API C.

.. c:member:: declaration¶

.. c:var:: declaration¶

Descreve uma variável ou um membro de struct C. Exemplo de assinatura:

.. c:member:: PyObject *PyTypeObject.tp_bases

A diferença entre as duas diretivas é apenas cosmética.

.. c:function:: function prototype¶

Descreve uma função C. A assinatura deve ser dada como em C, por exemplo:

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

Observe que você não precisa fazer a barra invertida para escapar asteriscos na assinatura, pois ela não é analisada pelo reStructuredText embutido.

Na descrição de uma função você pode usar os seguintes campos de informação (veja também Listas de campos de informações).

param, parameter, arg, argument: Descrição de um parâmetro.
type: Tipo de parâmetro, escrito como se fosse passado para o papel c:expr.
returns, return: Descrição do valor de retorno.
rtype: Tipo de retorno, escrito como se fosse passado para o papel c:expr.
retval, retvals: Uma alternativa a returns para descrever o resultado da função.

Adicionado na versão 4.3: O tipo de campo retval.

Por exemplo:

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

que é renderizado como

PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)¶

No-contents-entry:

No-index-entry:

Parâmetros:

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

Retorna:

a result.

Valores de retorno:

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

:single-line-parameter-list: (no value)¶: Garante que os parâmetros da função serão emitidos em uma única linha lógica, substituindo c_maximum_signature_line_length e maximum_signature_line_length.

Adicionado na versão 7.1.

.. c:macro:: name¶

.. c:macro:: name(arg list)

Descreve uma macro C, ou seja, uma #define da linguagem C, sem o texto de substituição.

Na descrição de uma macro você pode usar os mesmos campos de informação da diretiva c:function.

Adicionado na versão 3.0: A variante de estilo de função.

:single-line-parameter-list: (no value)¶: Garante que os parâmetros da macro serão emitidos em uma única linha lógica, substituindo c_maximum_signature_line_length e maximum_signature_line_length.

Adicionado na versão 7.1.

.. c:struct:: name¶: Descreve um struct de C.

Adicionado na versão 3.0.

.. c:union:: name¶: Descreve uma union de C.

Adicionado na versão 3.0.

.. c:enum:: name¶: Descreve um enum de C.

Adicionado na versão 3.0.

.. c:enumerator:: name¶: Descreve um enumerador de C.

Adicionado na versão 3.0.

.. c:type:: typedef-like declaration¶
.. c:type:: name: Descreve um tipo C, como typedef ou o alias de um tipo não especificado.

Referência cruzadas a construções C¶

Os papéis a seguir criam referências cruzadas para construções da linguagem C se forem definidas na documentação:

:c:member:¶
:c:data:¶
:c:var:¶
:c:func:¶
:c:macro:¶
:c:struct:¶
:c:union:¶
:c:enum:¶
:c:enumerator:¶
:c:type:¶: Faz referência a uma declaração C, conforme definido acima. Observe que c:member, c:data e c:var são equivalentes.

Adicionado na versão 3.0: Os papéis de var, struct, união, enum e enumerador.

Entidades anônimas¶

C oferece uniões, enums e structs anônimos. Para fins de documentação, eles devem receber algum nome que comece com @, por exemplo, @42 ou @data. Esses nomes também podem ser usados em referências cruzadas, embora símbolos aninhados sejam encontrados mesmo quando omitidos. O nome @... sempre será renderizado como [anonymous] (possivelmente como um link).

Exemplo:

.. c:struct:: Data

   .. c:union:: @data

      .. c:var:: int a

      .. c:var:: double b

Explicit ref: :c:var:`[email protected]`. Short-hand ref: :c:var:`Data.a`.

Isso será renderizado como:

struct Data¶

union [anonymous]¶

int a¶

double b¶

Referência explícita: Data.[anonymous].a. Referência abreviada: Data.a.

Adicionado na versão 3.0.

Fazendo alias de declarações¶

Às vezes, declarações de lista podem ser úteis em outros lugares além da documentação principal, por exemplo, ao criar uma sinopse de uma interface. A seguinte diretiva pode ser usada para esse propósito.

.. c:alias:: name¶

Insere uma ou mais declarações de alias. Cada entidade pode ser especificada como pode na função c:any.

Por exemplo:

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

.. c:alias:: data
             f

se torna

int data¶

int f(double k)¶

int data
int f(double k)

Adicionado na versão 3.2.

Opções

:maxdepth: int¶: Insere também declarações aninhadas, até a profundidade total fornecida. Use 0 para profundidade infinita e 1 apenas para a declaração mencionada. O padrão é 1.

Adicionado na versão 3.3.

:noroot:¶: Ignora as declarações mencionadas e renderiza apenas declarações aninhadas. Requer maxprofundidade 0 ou pelo menos 2.

Adicionado na versão 3.5.

Tipos e expressões em lniha¶

:c:expr:¶

:c:texpr:¶

Insere uma expressão C ou digite como código embutido (cpp:expr) ou texto embutido (cpp:texpr). Por exemplo:

.. 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*`).

será renderizado da seguinte maneira:

int a = 42¶

int f(int i)¶

Uma expressão: a * f(a) (ou como texto: a * f(a)).

Um tipo: const Data* (ou como texto const Data*).

Adicionado na versão 3.0.

Usando espaços de nomes¶

Adicionado na versão 3.1.

A linguagem C em si não oferece suporte o uso de espaço de nomes, mas às vezes pode ser útil emulá-lo na documentação, por exemplo, para mostrar declarações alternativas. O recurso também pode ser usado para documentar membros de structs/uniões/enums separados de sua declaração mãe.

O escopo atual pode ser alterado usando três diretivas de espaço de nomes. Eles gerenciam declarações de pilha onde c:namespace redefine a pilha e altera um determinado escopo.

A diretiva c:namespace-push altera o escopo para um determinado escopo interno do atual.

A diretiva c:namespace-pop desfaz a diretiva c:namespace-push mais recente.

.. c:namespace:: scope specification¶

Altera o escopo atual dos objetos subsequentes para o escopo especificado e redefine a pilha de diretivas de espaço de nomes. Observe que os escopos aninhados podem ser especificados separando-os com um ponto, por exemplo:

.. c:namespace:: Namespace1.Namespace2.SomeStruct.AnInnerStruct

Todos os objetos subsequentes serão definidos como se seus nomes tivessem sido declarados com o escopo anexado. As referências cruzadas subsequentes serão pesquisadas a partir do escopo atual.

Usar NULL ou 0 como escopo mudará para escopo global.

.. c:namespace-push:: scope specification¶

Altera o escopo relativamente ao escopo atual. Por exemplo, depois de:

.. c:namespace:: A.B

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

o escopo atual será A.B.C.D.

.. c:namespace-pop::¶

Desfaz a diretiva c:namespace-push anterior (não apenas abre um escopo). Por exemplo, depois de:

.. c:namespace:: A.B

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

.. c:namespace-pop::

o escopo atual será A.B (não A.B.C).

Se nenhuma diretiva c:namespace-push anterior tiver sido usada, mas apenas uma diretiva c:namespace, então o escopo atual será redefinido para o escopo global. Ou seja, .. c:namespace:: A.B é equivalente a:

.. c:namespace:: NULL

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

Variáveis de configuração¶

Veja Opções para o domínio C.