Como ser capaz de extrair comentários de dentro de uma função em doxygen?

Question

Estou interessado em saber se é possível ter alguns comentários em uma função (C, C ++, java) de uma forma que doxygen poderia colocá-los no arquivo HTML gerado.

Por exemplo:

function(...)
{
do_1();
/**
 * Call do_2 function for doing specific stuff.
 */ 
do_2();
}

Answer 1

Não, doxygen não suporta comentários blocos dentro de corpos de função. A partir do manual:

Doxygen permite que você coloque seus blocos de documentação praticamente em qualquer lugar (a exceção é dentro do corpo de uma função ou dentro de um bloco de comentário normal de estilo C).

Secção: Doxygen documentar o código

Answer 2

Eu não sei para C, mas eu faço isso todos os dias em Objective-C, onde tenho comentários como:

/// This method perform the following operations:
- (void) myMethodWith: (id) anObjectArgument
{
    /// - do op1
    [self op1];

    /// - do op2
    op2(anObjectArgument);
}

que processa como:

Este método executa a seguinte operações:

• fazer op1

• fazer op2

---

Editar:. seguinte comentário por Dana the Sane, sobre a minha compreensão da documentação Doxygen e por que ele não está em contradição com a minha experiência

Tanto quanto eu compreender e interpretar a documentação Doxygen, este não está em contradição com o Citação fornecido por Aaron Saarela . No início da ligação, ele fornece, há um parágrafo sobre a documentação no corpo:

Para cada item de código há duas (ou em alguns casos três) tipos de as descrições, as quais juntas formam o documentação: uma descrição breve e descrição detalhada, ambos são opcional. Para os métodos e funções há também um terceiro tipo de descrição, o chamado "no corpo" descrição, que consiste na concatenação de todos os blocos de comentário encontrado dentro do corpo do método ou função.

Isto significa que é ok para colocar a documentação Doxygen em uma função ou método corpo. Isto é o que eu descrevi em cima da minha resposta.

Na minha opinião, o parágrafo citado por Aaron refere-se a documentação que normalmente é colocado na frente de função ou método declaração ou implementaiton. Esta é a única que descreve parâmetros, valores de retorno e assim por diante. Que direção documentação não pode ser colocado dentro do corpo de uma função ou método.

Mas a documentação detalhada sobre cada etapa de um algoritmo dentro de um corpo está perfeitamente tratado pelo Doxygen.

Answer 3

comentários dentro do código são destinadas a explicar um trecho de implementação específica para outro programador para entender, não é uma característica da função para os usuários a ler sobre.

Se ele tem que ser documentado para os usuários, isso deve ser feito ouside o bloco de função, em um comentário que define a interface (assinatura, bem como pré-condições, pós-condições, exemplos de uso ou o que você julga necessário ).

Answer 4

Talvez em vez você pode colocar o código da função como um exemplo. http://www.doxygen.nl/manual/commands.html#cmdexample