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

97

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?

Singulus
fuente

Respuestas:

77

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.

Andy Dent
fuente
11
He tenido un doloroso recordatorio de por qué se deben evitar los documentos en los encabezados: un vicepresidente senior me dijo que pusiera los comentarios del método en la declaración de la clase y me encontré guardando las ediciones de comentarios para más adelante porque presionar esos encabezados desencadena un tiempo de compilación de 45 minutos. !
Andy Dent
7
No votar negativamente, solo cuestionar: si estoy tratando de averiguar qué hace una API (incluso una interna), prefiero no tener que abrir el .cpp y revisar todo el código para encontrar la documentación. Admito que sería una molestia documentar algo más que la opinión del cliente sobre lo que hace el método (como cómo lo hace), pero no debería hacerlo de todos modos, ¿verdad?
TED
8
El objetivo de usar Doxygen para generar su documentación es tener la documentación generada accesible. Tenemos un servidor web interno donde va la salida de Doxygen y luego podemos usar enlaces a las páginas de ese servidor en las discusiones. Eso también une la documentación de clases o métodos con páginas adicionales que discuten cuestiones de diseño más amplias.
Andy Dent
1
Decidir qué tan público debe ser el debate sobre la implementación es un tema interesante. Ciertamente, si hay un algoritmo o efectos secundarios en particular, preferiría conocerlos como cliente de la biblioteca. A veces, solo el mantenedor debe saberlo y Doxygen tiene una manera fácil de marcar secciones condicionales, por lo que puede generar diferentes documentos para diferentes puntos de vista.
Andy Dent
76

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;
}
Daniel Buckmaster
fuente
3
Me gusta este método, pero parece incompatible con AUTOBRIEF. Me interesaría saber si existe una solución alternativa de configuración para eliminar los múltiples resúmenes que se producen.
Aaron Wright
También me gusta este método, proporciona un buen equilibrio en la implementación.
Xofo
No puedo reproducir este método en mi máquina, usando Doxygen 1.8.15. No aparece la documentación de los parámetros, solo las descripciones breves y detalladas.
punyidea
1
Anexo: Cambiar la ubicación de la descripción detallada dentro del bloque de la función hizo que esto funcionara para mí. La descripción ahora se adjunta al final de las descripciones en los documentos del encabezado.
punyidea
18

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.


fuente
Correcto, pero es un gran problema si es una biblioteca dinámica recuperada de un artefactor y no tiene los archivos fuente :-)
DrumM
12

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.

eaanon01
fuente
2
¿Cuándo se copia el bloque?
Mert Can Ergün
2

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.

Mouviciel
fuente
2

Pongo todo en el archivo de encabezado.

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

graham.reeds
fuente
2

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.

Sinclair
fuente
-1

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.

Kelvin
fuente