code - Usando Doxygen con C, ¿comenta la función prototipo o la definición? ¿O ambos?
doxygen tutorial (5)
A menudo utilizo Doxygen con C para sistemas embebidos. Intento escribir documentación para cualquier objeto en un solo lugar, porque la duplicación resultará en confusión más adelante. Doxygen hace una cierta cantidad de fusión de los documentos, por lo que en principio es posible documentar la API pública en el archivo .h , y tener algunas notas sobre cómo funciona realmente en el archivo .c . He intentado no hacerlo yo mismo.
Si mover los documentos de un lugar a otro cambia la cantidad de advertencias que produce, puede indicar que puede haber algo sutilmente diferente entre la declaración y la definición. ¿El código se compila limpio con -Wall -Wextra por ejemplo? ¿Hay macros que mutan el código en un lugar y no en el otro? Por supuesto, el analizador de Doxygen no es un analizador de lenguaje completo, y también es posible confundirlo.
Estoy usando Doxygen con alguna fuente C incrustada. Dado un par de archivos .c / .h, ¿coloca los comentarios de Doxygen en la función prototype (archivo .h) o la definición de la función (archivo .c), o los duplica en ambos lugares?
Tengo un problema en el que Doxygen advierte sobre los comentarios faltantes cuando documenta en un lugar pero no en el otro; es esto esperado, o es mi Doxygen jodido?
Citado en mi respuesta a esta pregunta: documentación del archivo de encabezado C / C ++ :
Pongo la documentación para la interfaz (parámetros, valor de retorno, lo que hace la función) en el archivo de interfaz (.h), y la documentación para la implementación ( cómo funciona la función) en el archivo de implementación (.c, .cpp,. metro). Escribo un resumen de la clase justo antes de su declaración, por lo que el lector tiene información básica inmediata.
Con Doxygen, esto significa que la documentación que describe la descripción general, los parámetros y los valores de retorno ( /brief , /param , /return ) se utilizan para documentar la función prototipo y la documentación en línea ( /details ) se utiliza para documentar el cuerpo de la función (también puede consultar mi Responda a esa pregunta: ¿Cómo poder extraer comentarios desde dentro de una función en doxygen? )
Me hice la misma pregunta y me sorprendió gratamente al ver que Doxygen en realidad incluye la misma documentación en línea que se encuentra en el archivo .c en el archivo .h correspondiente al examinar la documentación html generada. Por lo tanto, no tiene que repetir su documentación en línea, ¡y Doxygen es lo suficientemente inteligente como para incluirlo en ambos lugares!
Estoy ejecutando la versión Doxygen versión 1.8.10.
Para las API públicas, documento en la declaración, ya que aquí es donde el usuario generalmente mira primero si no está utilizando la salida de doxygen.
Nunca tuve problemas con solo documentar en un solo lugar, pero lo usé con C ++; Podría ser diferente con C, aunque lo dudo.
[editar] Nunca lo escribas dos veces. Nunca. La documentación en la fuente también está SECA, especialmente en lo que respecta a tales perversiones de copiar y pegar. [/ Editar]
Sin embargo, puede especificar si desea advertencias para elementos no documentados . Aunque estas advertencias parecen agradables en teoría, mi experiencia es que rápidamente son más una carga que una ayuda. Documentar todas las funciones generalmente no es el camino a seguir (tal cosa es la documentación redundante, o incluso obstaculizar la documentación, y sobre todo demasiada documentación); una buena documentación necesita que una persona bien informada pase tiempo con ella. Dado eso, esas advertencias son innecesarias.
Y si no tiene los recursos para escribir una buena documentación (dinero, tiempo, lo que sea ...), esas advertencias tampoco ayudarán.
Solo comentamos las definiciones de funciones, pero las usamos con C ++.
Escribirlo en ambos lugares es perder el tiempo. Acerca de la advertencia, si su documentación se ve bien, tal vez sea una buena manera de ignorar tales advertencias.