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?
fonte
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
mymodule.cpp
fonte
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
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
MEU arquivo1.c
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.
fonte
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.
fonte
Coloquei tudo no arquivo de cabeçalho.
Documento tudo, mas geralmente extraio a interface pública.
fonte
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!
fonte
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.
fonte