¿Los mejores consejos para documentar el código usando doxygen? [closed]

Question 1

Mi equipo está comenzando a documentar nuestro código C usando doxygen, prestando especial atención a nuestros encabezados de API públicos. Parece haber mucha flexibilidad y diferentes comandos especiales en doxygen, lo cual es genial, pero no está claro qué es bueno y qué es malo sin prueba y error.

¿Cuáles son sus formas favoritas de marcar su código, cuáles son lo que DEBE HACER y lo que NO DEBE HACER?
Proporcione sus mejores sugerencias, una por respuesta para facilitar la votación.

Busco definir todo nuestro enfoque de la documentación de la API, incluida la provisión de una plantilla para que el resto del equipo comience. Hasta ahora tengo algo como esto:

/**
 * @file   example_action.h
 * @Author Me (me@example.com)
 * @date   September, 2008
 * @brief  Brief description of file.
 *
 * Detailed description of file.
 */

/**
 * @name    Example API Actions
 * @brief   Example actions available.
 * @ingroup example
 *
 * This API provides certain actions as an example.
 *
 * @param [in] repeat  Number of times to do nothing.
 *
 * @retval TRUE   Successfully did nothing.
 * @retval FALSE  Oops, did something.
 *
 * Example Usage:
 * @code
 *    example_nada(3); // Do nothing 3 times.
 * @endcode
 */
boolean example(int repeat);

Question 2

No necesita y no debe escribir el nombre del archivo en el @file directiva, doxygen lee el nombre del archivo automáticamente. El problema de escribir el nombre del archivo es que cuando cambie el nombre del archivo tendrá que cambiar el @file directiva también.

Proporcionar @author y @date la información también es inútil la mayor parte del tiempo, ya que el sistema de control de fuente lo hace mucho mejor que alguien que edita los archivos manualmente.

Tampoco tienes que escribir @brief si usa la siguiente sintaxis de Doxygen y habilita JAVADOC_AUTOBRIEF en la configuración de doxygen:

/*! Short Description on the first line

    Detailed description...
    ...
*/
void foo(void) {}

Él @name La directiva para funciones también es 100% redundante la mayor parte del tiempo y completamente inútil. Solo trae errores cuando alguien modifica el nombre de la función y no el doxygen @name.

Question 3

Escribe un página de inicio descriptiva usando @mainpage (en un archivo de encabezado separado solo para este propósito). Considere, como se muestra en mi ejemplo, convertirlo en una guía para sus principales clases/funciones y módulos.

otra muestra

Mientras estaba volviendo a poner en línea el contenido de doxygen de oofile principal vinculado anteriormente, aquí hay un ejemplo de un trabajo de cliente actual que usa el formato Markdown. Al usar Markdown, puede consultar una página principal en Markdown (en la configuración de Doxygen), lo cual es excelente para el típico readme.md archivo incluido en proyectos de código abierto.

Lingopal
========
Developer Documentation started when Andy Dent took over support in May 2014. 

There are a number of pages in Markdown format which explain key aspects:

- @ref doc/LingopalBuilding.md
- @ref doc/LingopalSigning.md
- @ref doc/LingopalDatabases.md
- @ref doc/LingopalExternals.md

See the <a href="https://stackoverflow.com/questions/51667/pages.html">Related Pages list for more.</a>

-------------

_Note_

These pages, whilst readable by themselves, are designed to be run through the [Doxygen](http://www.doxygen.com) code documentation engine which builds an entire local cross-referenced set of docs. It uses a minor [extension of Markdown formatting.](http://www.stack.nl/~dimitri/doxygen/manual/markdown.html)

The settings to generate the documentation are `Lingopal.doxy` and `LingopalDocOnly.doxy`. The latter is used for quick re-generation of just these additional pages.

Question 4

Utilizar Grupos para organizar su código en módulos.

Recuerde que puede poner casi todo en varios grupos para que puedan usarse para proporcionar etiquetas semánticas como las etiquetas en Stack Overflow. Por ejemplo, puede etiquetar cosas como específicas de una plataforma determinada.

También puede usar grupos para hacer coincidir un jerarquía de carpetas dentro de un IDEcomo se muestra en mi muestra RB2Doxy producción.

Los grupos funcionan bien cuando están anidados; tengo un gran ejemplo para el fuente OOFILE.

Question 5

Algunos comandos que uso en mi código:

\todo { paragraph describing what is to be done } Útil para realizar un seguimiento de todos, se creará una página en la documentación final que contiene su lista de tareas pendientes.
\c <word> Muestra el argumento utilizando una fuente de máquina de escribir. Use esto para referirse a una palabra de código. Lo usaría antes de “VERDADERO” y “FALSO” en su ejemplo.
\a , \warning , \see : ver http://www.stack.nl/~dimitri/doxygen/commands.html#cmdc para descripción

Question 6

Una buena “práctica recomendada” (aunque no siempre alcanzable) es proporcionar ejemplos breves y prácticos para cada API e incluirlos en la ayuda usando \includelineno (o \include para no tener números de línea). Estas pueden ser pruebas unitarias, si están escritas para que los usuarios puedan entenderlas (es decir, no enganchadas a un arnés de prueba más grande). Como un buen efecto secundario, los cambios en la API romperán las muestras, por lo que deben mantenerse actualizadas.

Puede describir una API con palabras, pero no hay nada como ver el código real para entender cómo usarlo.

Question 7

A medida que me encuentro editando código en pantallas de mayor resolución, he pasado de usar la barra invertida al prefijo @ en los comandos de Doxygen. no tan ruidoso barra invertida se ha encontrado ahora demasiado difícil de distinguir los comandos de Doxygen.

Question 8

Si está seguro de que su equipo seguirá una plantilla tan pesada, está bien, utilícela como se muestra.

De lo contrario, se parece a JavaDoc. Una de las cosas buenas de Doxygen es lo bien que funciona. sin que tener que usar un marcado tan fuerte. No necesita usar @name y con la configuración JAVADOC_AUTOBRIEF puede omitir @brief; solo asegúrese de que la primera línea del comentario sea una breve descripción razonable.

Prefiero los nombres descriptivos en lugar de hacer cumplir la documentación y alentar a las personas a agregar comentarios solo cuando agregan un valor significativo. De esa manera, los comentarios valiosos no se ahogan por todos los ruido.

¿Ha sido útil esta solución?