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

Question

O senso comum diz que os blocos de comentários Doxygen tem que ser colocado nos arquivos de cabeçalho, onde as classes, estruturas, enums, funções, declarações são. Concordo que este é um argumento sólido por bibliotecas que são más para ser distribuído sem a sua fonte (apenas cabeçalhos e libs com código de objeto).

Mas ... Eu estive pensando na abordagem exatamente oposta quando eu estou desenvolvendo um interno à empresa (ou como um projeto paralelo para mim) biblioteca que será usado com o seu código fonte completo. O que eu proponho é colocar os grandes blocos de comentários nos arquivos de implementações (HPP, INL, CPP, etc), para não atravancar a inteface das classes e funções declaradas no cabeçalho.

Pros:

• Menos desordem nos arquivos de cabeçalho, apenas a categorização das funções podem ser adicionadas.
• Os blocos de comentários que são pré-visualizados quando Intellisense por exemplo, é usado não choca - este é um defeito que tenho observado quando eu tenho um comentário em bloco para uma função no arquivo .H e ter a sua definição em linha na mesma ficheiro.h mas incluía a partir do arquivo .INL.

Contras:

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

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

Answer 1

Coloque a documentação onde as pessoas vão ler e escrevê-lo como eles estão usando e trabalhando no código.

comentários Classe ir na frente de aulas, os comentários método na frente de métodos.

Essa é a melhor maneira de certificar-se de que as coisas estão mantidos. Ele também mantém seus arquivos de cabeçalho relativamente magra e evita o tocar questão das pessoas atualizando docs método causando cabeçalhos para estar sujo e reconstrói desencadeantes. Tenho pessoas realmente conhecidas usar isso como uma desculpa para escrever documentação mais tarde!

Answer 2

Eu gosto de fazer uso do fato de que os nomes podem ser documentadas em vários lugares.

No arquivo de cabeçalho, eu escrever uma breve descrição do método, e documentar todos os seus parâmetros - estes são menos propensos a mudança do que a implementação do método em si, e se o fizerem, então as necessidades de protótipo função para ser alterado em qualquer caso.

Eu coloquei documentação de longo formato nos arquivos de origem ao lado da implementação real, assim que os detalhes podem ser alteradas com a evolução do método.

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;
}

Answer 3

Tendo comentários nos meios de cabeçalho que todos os usuários de uma classe devem ser recompilados se um comentário é alterado. Para um grande projectos, codificadores estarão menos inclinados a comentários de atualização nos cabeçalhos se arriscar passar a próxima 20min reconstruir tudo.

E .. desde que você deveria ler o doc html e não navegar através do código para a documentação, não é um grande problema que os blocos de comentários são mais difíceis de localizar nos arquivos de origem.

Answer 4

cabeçalhos: Mais fácil de ler os comentários já que há menos outro "ruído" quando se olha para os arquivos.

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

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

Você pode no entanto também obter os resultados copiados para diferentes documentos de arquivo com um simples comando. Por exemplo. : -

Meu file1.h

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

MY file1.c

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

Agora você começa a mesma documentação em ambas as funções.

Isto dá-lhe menos ruído nos arquivos de código, ao mesmo tempo que você começa a documentação escrita em um lugar apresentou em vários lugares na saída final.

Answer 5

Normalmente eu colocar a documentação para a interface (\ param, \ retorno) em ficheiro.h e documentação para a implementação (\ detalhes) em .c / CPP / .m arquivo. Doxygen grupos tudo na documentação função / método.

Answer 6

Eu coloquei tudo no cabeçalho do arquivo.

Eu documento tudo, mas apenas geralmente extrair a interface pública.

Answer 7

Eu estou usando QtCreator para a programação. Um truque muito útil consiste em Ctrl-Clicando sobre uma função ou método para obter a declaração no arquivo de cabeçalho.

Quando o método é comentado no cabeçalho do arquivo, você pode encontrar rapidamente a informação que você está procurando. Então, para mim, os comentários devem ser localizados no arquivo de cabeçalho!

Answer 8

Em C ++, por vezes, a execução pode ser dividida entre os módulos de cabeçalho e .cpp. Aqui parece mais limpo para colocá-lo a documentação em arquivo de cabeçalho, que é o único lugar em que todas as funções públicas e métodos são garantidos.