documentation - lenguaje - ¿Dónde colocar los bloques de comentarios de doxígeno para una biblioteca interna, en H o en archivos CPP?

tipos de comentarios en lenguaje c

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 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 entran en conflicto; 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 desde el archivo .INL.

Contras:

• (El más obvio) Los bloques de comentarios no están en los archivos de encabezado donde están las declaraciones.

Entonces, ¿qué piensas y posiblemente sugieres?

Answer 1

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

Los comentarios de clase van en frente de las clases, los comentarios de métodos en frente de los métodos.

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

Answer 2

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.

Answer 3

Estoy usando QtCreator para programar. 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 el método se comenta 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 4

Me gusta utilizar el hecho de que los nombres se pueden documentar en múltiples 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. .

Puse documentación de formato largo en los archivos fuente 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 5

Normalmente pongo 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.

Answer 6

Puse todo en el archivo de encabezado.

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

Answer 7

Tener comentarios en el encabezado significa que todos los usuarios de una clase deben recompilarse 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 ... dado que se supone que debe 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 localizar en los archivos fuente.

Answer 8

Encabezados: es más fácil 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.

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 obtener los resultados copiados en diferentes documentos de archivo con un simple comando. P.ej :-

Mi archivo1.h

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

MI archivo1.c

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

Ahora obtienes la misma documentación en ambas funciones.

Esto le proporciona menos ruido en los archivos de código al mismo tiempo que obtiene la documentación escrita en un lugar presentado en varios lugares en el resultado final.