El sentido común dice que los bloques de comentarios de Doxygen deben colocarse en los archivos de encabezado donde se encuentran las clases, estructuras, enumeraciones, funciones y declaraciones. Estoy de acuerdo en que este es un argumento sólido para las bibliotecas que deben distribuirse sin su fuente (solo encabezados y bibliotecas con código objeto).
PERO ... He estado pensando en el enfoque exactamente opuesto cuando estoy desarrollando una biblioteca interna de la empresa (o como un proyecto paralelo para mí) que se utilizará con su código fuente completo. Lo que propongo es poner los grandes bloques de comentarios en los archivos de implementación (HPP, INL, CPP, etc.) para NO desordenar la interfaz de las clases y funciones declaradas en el encabezado.
Pros:
- Menos desorden en los archivos de encabezado, solo se puede agregar la categorización de las funciones.
- Los bloques de comentarios que se previsualizan cuando se usa Intellisense, por ejemplo, no chocan; este es un defecto que he observado cuando tengo un bloque de comentarios para una función en el archivo .H y tengo su definición en línea en el mismo archivo .H pero incluido en el archivo .INL.
Contras:
- (El obvio) Los bloques de comentarios no están en los archivos de encabezado donde están las declaraciones.
Entonces, ¿qué piensas y posiblemente sugieres?