¿Dónde colocar los bloques de comentarios de Doxygen para una biblioteca interna, en archivos H o CPP? [cerrado]

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?

Coloque la documentación en un lugar donde la gente la lea y escriba a medida que usa y trabaja en el código.

Los comentarios de la clase van delante de las clases, los comentarios de los métodos delante de los métodos.

Esa es la mejor manera de asegurarse de que las cosas se mantengan. También mantiene sus archivos de encabezado relativamente esbeltos y evita el conmovedor problema de que las personas actualicen los documentos de métodos, lo que hace que los encabezados estén sucios y activen reconstrucciones. De hecho, he conocido que la gente usa eso como una excusa para escribir documentación más tarde.

Me gusta aprovechar 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 cambiarse 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;
}

Tener comentarios en el encabezado significa que todos los usuarios de una clase deben volver a compilarse si se cambia un comentario. Para proyectos grandes, los programadores estarán menos dispuestos a actualizar los comentarios en los encabezados si se arriesgan a pasar los próximos 20 minutos reconstruyendo todo.

Y ... dado que se supone que debe leer el documento html y no navegar por el código en busca de documentación, no es un gran problema que los bloques de comentarios sean más difíciles de localizar en los archivos fuente.

Encabezados: es más fácil leer los comentarios ya que hay menos "ruido" al mirar los archivos.

Fuente: Entonces tienes las funciones reales disponibles para leer mientras miras los comentarios.

Solo usamos 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, también puede copiar los resultados en una documentación de archivo diferente con un comando simple. P.ej :-

Mi archivo1.h

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

MI file1.c

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

Ahora obtienes la misma documentación sobre ambas funciones.

Esto le brinda menos ruido en los archivos de código al mismo tiempo que obtiene la documentación escrita en un solo lugar presentada en varios lugares en la salida final.

Por lo general, pongo la documentación para la interfaz (\ param, \ return) en el archivo .h y la documentación para la implementación (\ details) en el archivo .c / .cpp / .m. Doxygen agrupa todo en la documentación de la función / método.

Pongo todo en el archivo de encabezado.

Documento todo, pero solo extraigo generalmente la interfaz pública.

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

Cuando se comenta el método en el archivo de encabezado, puede encontrar rápidamente la información que está buscando. Entonces, para mí, los comentarios deben ubicarse en el archivo de encabezado.

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