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

votos
83

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

prós:

  • Menos desordem nos arquivos de cabeçalho, pode ser adicionado apenas categorização das funções.
  • 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 no mesmo arquivo .H mas incluía a partir do arquivo .INL.

contras:

  • (A mais óbvia) A 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?

Publicado 10/12/2008 em 11:23
fonte usuário
Em outras línguas...                            


8 respostas

votos
66

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 de classe ir na frente de classes, 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 a tocar questão das pessoas atualizando docs método causando cabeçalhos para ser reconstruções sujos e desencadeantes. Eu, na verdade conhecido pessoas usam isso como uma desculpa para escrever documentação mais tarde!

Respondeu 15/01/2009 em 00:18
fonte usuário

votos
50

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

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

Coloquei documentação de longo formato nos arquivos de origem ao lado da implementação real, assim que os detalhes podem ser alteradas 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;
}
Respondeu 12/10/2011 em 09:23
fonte usuário

votos
14

Ter comentários no cabeçalho significa 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 atualizar comentários em cabeçalhos de se arriscar a 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.

Respondeu 09/01/2009 em 15:22
fonte usuário

votos
9

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ê poderia, contudo, 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.

Respondeu 10/12/2008 em 11:39
fonte usuário

votos
3

Coloquei tudo no arquivo de cabeçalho.

I documentar tudo, mas apenas geralmente extrair a interface pública.

Respondeu 08/01/2009 em 11:29
fonte usuário

votos
3

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

Respondeu 05/01/2009 em 16:06
fonte usuário

votos
2

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!

Respondeu 24/09/2012 em 21:34
fonte usuário

votos
0

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.

Respondeu 15/11/2013 em 21:06
fonte usuário

Cookies help us deliver our services. By using our services, you agree to our use of cookies. Learn more