Onde colocar os blocos de comentário doxygen para uma biblioteca interna - em arquivos H ou CPP? [fechadas]

O bom senso diz que os blocos de comentário do Doxygen devem ser colocados nos arquivos de cabeçalho onde estão as classes, estruturas, enums, funções e declarações. Concordo que este é um bom argumento para bibliotecas que devem ser distribuídas sem sua fonte (apenas cabeçalhos e bibliotecas com código-objeto).

MAS ... Eu tenho pensado na abordagem exatamente oposta quando estou desenvolvendo uma biblioteca interna para a empresa (ou como um projeto paralelo para mim) que será usada com seu código-fonte completo. O que proponho é colocar os grandes blocos de comentários nos arquivos de implementação (HPP, INL, CPP, etc) para NÃO bagunçar a interface das classes e funções declaradas no cabeçalho.

Prós:

• Menos confusão nos arquivos de cabeçalho, apenas a categorização das funções pode ser adicionada.
• Os blocos de comentário que são visualizados quando o Intellisense, por exemplo, é usado, não entram em conflito - este é um defeito que observei quando tenho um bloco de comentário para uma função no arquivo .H e tenho sua definição embutida no mesmo arquivo .H mas incluído no arquivo .INL.

Contras:

• (O mais óbvio) Os blocos de comentário não estão nos arquivos de cabeçalho onde as declarações estão.

Então, o que você acha e possivelmente sugere?

Coloque a documentação onde as pessoas irão ler e escrever à medida que estiverem usando e trabalhando no código.

Os comentários das classes vão antes das classes, os comentários dos métodos vão antes dos métodos.

Essa é a melhor maneira de garantir que as coisas sejam mantidas. Ele também mantém seus arquivos de cabeçalho relativamente enxutos e evita o problema tocante de pessoas atualizando documentos de métodos, fazendo com que os cabeçalhos fiquem sujos e acionando reconstruções. Na verdade, sei que pessoas usam isso como desculpa para escrever documentação mais tarde!

Gosto de aproveitar o fato de que os nomes podem ser documentados em vários lugares.

No arquivo de cabeçalho, escrevo uma breve descrição do método e documento todos os seus parâmetros - eles são menos propensos a mudar do que a implementação do próprio método e, se mudarem, então o protótipo da função precisa ser alterado em qualquer caso .

Eu coloquei a documentação de formato longo nos arquivos de origem ao lado da implementação real, para que os detalhes possam ser alterados conforme o método evolui.

Por exemplo:

mymodule.h

/// @brief This method adds two integers.
/// @param a First integer to add.
/// @param b Second integer to add.
/// @return The sum of both parameters.
int add(int a, int b);

mymodule.cpp

/// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// @TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
  return b + a;
}

Ter comentários no cabeçalho significa que todos os usuários de uma classe devem ser recompilados se um comentário for alterado. Para projetos grandes, os programadores estarão menos inclinados a atualizar os comentários nos cabeçalhos se correrem o risco de gastar os próximos 20 minutos reconstruindo tudo.

E .. já que você deve ler o documento html e não navegar pelo código para obter a documentação, não é um grande problema que os blocos de comentário sejam mais difíceis de localizar nos arquivos de origem.

Cabeçalhos: Mais fácil de ler os comentários, pois há menos outro "ruído" ao olhar para os arquivos.

Fonte: então você tem as funções reais disponíveis para leitura enquanto olha os comentários.

Apenas usamos todas as funções globais comentadas nos cabeçalhos e funções locais comentadas no código-fonte. Se você quiser, também pode incluir o comando copydoc para inserir a documentação em vários lugares sem ter que escrever várias vezes (melhor para manutenção)

No entanto, você também pode obter os resultados copiados para documentação de arquivo diferente com um comando simples. Por exemplo :-

Meu arquivo1.h

/**
 * \brief Short about function
 *
 * More about function
 */
WORD my_fync1(BYTE*);

MEU arquivo1.c

/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}

Agora você obtém a mesma documentação sobre as duas funções.

Isso proporciona menos ruído nos arquivos de código ao mesmo tempo em que obtém a documentação escrita em um local apresentado em vários locais na saída final.

Normalmente eu coloco a documentação da interface (\ param, \ return) no arquivo .h e a documentação para implementação (\ details) no arquivo .c / .cpp / .m. O Doxygen agrupa tudo na documentação da função / método.

Coloquei tudo no arquivo de cabeçalho.

Documento tudo, mas geralmente extraio a interface pública.

Estou usando o QtCreator para programação. Um truque muito útil consiste em clicar com a tecla Ctrl pressionada em uma função ou método para obter a declaração no arquivo de cabeçalho.

Quando o método é comentado no arquivo de cabeçalho, você pode encontrar rapidamente as informações que está procurando. Portanto, para mim, os comentários devem estar localizados no arquivo de cabeçalho!

Em c ++, às vezes, a implementação pode ser dividida entre módulos de cabeçalho e .cpp. Aqui, parece mais limpo colocar a documentação no arquivo de cabeçalho, pois é o único lugar que todas as funções e métodos públicos são garantidos.