Dónde colocar los bloques de comentario doxygen para una biblioteca interna - en H o en archivos CPP?

Question

El sentido común dice que los bloques de comentarios de Doxygen deben colocarse en los archivos de encabezado donde están las clases, estructuras, enumeraciones, funciones, declaraciones. Estoy de acuerdo en que este es un argumento sólido para las bibliotecas que están destinadas a ser distribuidas sin su fuente (solo encabezados y libs con código de objeto).

PERO ... He estado pensando en el enfoque exactamente opuesto cuando estoy desarrollando una biblioteca interna a la empresa (o como un proyecto paralelo para mí) que se utilizará con su código fuente completo. Lo que propongo es colocar los bloques de comentarios grandes en los archivos de implementación (HPP, INL, CPP, etc.) para no saturar la interfaz de las clases y funciones declaradas en el encabezado.

Pros:

• Menos desorden en los archivos de cabecera, sólo se pueden añadir categorización de las funciones.
• Los bloques de comentarios que se ven de antemano cuando Intellisense, por ejemplo, se utiliza no entrar en conflicto - este es un defecto que he observado cuando tengo un bloque de comentario a una función en el archivo .H y tienen su definición en línea de la misma .H archivo pero incluido desde el archivo .INL.

Contras:

• (la más obvia) Los bloques de comentarios no están en los archivos de cabecera cuando las declaraciones son.

Así que, ¿qué te parece y posiblemente sugiere?

Answer 1

Coloque la documentación donde las personas la leerán y escribirán mientras usan y trabajan en el código.

Los comentarios de clase van por delante de las clases, los comentarios de métodos están delante de los métodos.

Esa es la mejor manera de asegurarse de que todo se mantenga. También mantiene sus archivos de encabezado relativamente delgados y evita el tocando el problema de las personas que actualizan los documentos del método, lo que hace que los encabezados estén sucios y desencadenando reconstrucciones. ¡De hecho, he sabido que la gente lo usa como excusa para escribir documentación más tarde!

Answer 2

Encabezados: Más fácil de leer los comentarios ya que hay menos otros "ruidos" al mirar los archivos.

Fuente: Luego tiene las funciones reales disponibles para leer mientras mira los comentarios.

Acabamos de utilizar todas las funciones globales comentadas en los encabezados y las funciones locales comentadas en la fuente. Si lo desea, también puede incluir el comando copydoc para insertar la documentación en varios lugares sin tener que escribirla varias veces (mejor para el mantenimiento)

Sin embargo, puede obtener los resultados copiados en diferentes documentos con un simple comando . P.ej. : -

Mi file1.h

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

MI Archivo1.c

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

ya que usted consigue la misma documentación en ambas funciones.

Esto le da menos ruido en los archivos de código en el mismo momento de recibir la documentación escrita en un solo lugar presentado en varios lugares en la salida final.

Answer 3

Por lo general, puse la documentación para la interfaz (\ param \ retorno) en el archivo .h y documentación para la aplicación (\ detalles) en el archivo .c/Cpp/.m. Doxygen agrupa todo en la documentación de la función/método.

Answer 4

Puse todo en el archivo de encabezado.

Documentaré todo, pero generalmente solo extraeré la interfaz pública.

Answer 5

Tener comentarios en el encabezado significa que todos los usuarios de una clase deben volver a compilarse si se modifica un comentario. Para proyectos grandes, los codificadores estarán menos inclinados a actualizar los comentarios en los encabezados si corren el riesgo de pasar los siguientes 20 minutos reconstruyendo todo.

Y ... ya que se supone que debes leer el documento html y no buscar la documentación en el código, no es un gran problema que los bloques de comentarios sean más difíciles de encontrar en los archivos fuente.

Answer 6

Me gusta utilizar el hecho de que los nombres se pueden documentar en varios lugares.

En el archivo de encabezado, escribo una breve descripción del método, y documento todos sus parámetros; es menos probable que cambien que la implementación del método en sí, y si lo hacen, entonces el prototipo de la función debe ser cambiado en cualquier caso.

Pongo la documentación de formato largo en los archivos de origen junto a la implementación real, por lo que los detalles se pueden cambiar a medida que evoluciona el método.

Por ejemplo:

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 7

estoy usando QtCreator para la programación. Un truco muy útil consiste en Ctrl-clic en una función o método para obtener la declaración en el archivo de encabezado.

Cuando se comente el método en el archivo de encabezado, puede encontrar rápidamente la información que está buscando. Entonces, para mí, ¡los comentarios deberían estar ubicados en el archivo de encabezado!

Answer 8

En C++ a veces la implementación se puede dividir entre los módulos de encabezado y .cpp. Aquí parece más limpio poner su documentación en el archivo de encabezado, ya que es el único lugar donde se garantizan todas las funciones y métodos públicos.