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

97

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?

Singulus
fonte

Respostas:

77

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!

Andy Dent
fonte
11
Tive um doloroso lembrete de por que documentos em cabeçalhos devem ser evitados - fui informado por um vice-presidente sênior para colocar comentários de método na declaração de classe e me peguei salvando edições de comentários para mais tarde porque acertar esses cabeçalhos desencadeia um tempo de construção de 45 minutos !
Andy Dent,
7
Não downvoting, apenas questionando: se estou tentando descobrir o que uma API (mesmo interna) faz, prefiro não ter que abrir o .cpp e vasculhar todo o código para encontrar a documentação. Admito que seria uma dor se você documentasse mais do que apenas a visão do cliente sobre o que o método está fazendo (por exemplo, como ele faz), mas você não deveria fazer isso de qualquer maneira, certo?
TED de
8
O objetivo de usar o Doxygen para gerar sua documentação é ter a documentação gerada acessível. Temos um servidor web interno para onde vai a saída do Doxygen e podemos usar links para páginas desse servidor nas discussões. Isso também une a documentação de classe ou método com páginas adicionais que discutem questões mais amplas de design.
Andy Dent
1
Decidir quão pública a discussão da implementação deve ser é uma questão interessante. Certamente, se houver um algoritmo ou efeitos colaterais específicos, eu preferiria saber sobre eles como cliente da biblioteca. Às vezes, apenas o mantenedor deve saber e o Doxygen tem uma maneira fácil de marcar seções condicionais, então você pode gerar documentos diferentes para pontos de vista diferentes.
Andy Dent
76

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;
}
Daniel Buckmaster
fonte
3
Eu gosto desse método, mas parece ser incompatível com AUTOBRIEF. Eu estaria interessado em saber se há uma solução alternativa de configuração para eliminar os vários resumos que são produzidos.
Aaron Wright
Eu também gosto desse método, ele fornece um bom equilíbrio na implementação.
Xofo
Não consigo reproduzir este método na minha máquina, usando o Doxygen 1.8.15. A documentação dos parâmetros não aparece, apenas as descrições breves e detalhadas.
punyidea
1
Adendo: Mudar o posicionamento da descrição detalhada para dentro do bloco da função fez este trabalho para mim. A descrição agora está anexada ao final das descrições nos documentos do cabeçalho.
punyidea
18

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.


fonte
Correto, mas é um grande problema se for uma biblioteca dinâmica recuperada de um artefato e você não tiver os arquivos de origem :-)
DrumM
12

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.

eaanon01
fonte
2
quando o bloco é copiado?
Mert Can Ergün
2

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.

mouviciel
fonte
2

Coloquei tudo no arquivo de cabeçalho.

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

graham.reeds
fonte
2

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!

Sinclair
fonte
-1

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.

Kelvin
fonte