Al fin después de tanto trabajar ya hallamos la respuesta de esta incógnita que algunos lectores de esta web han presentado. Si tienes alguna información que compartir puedes dejar tu comentario.
Solución:
-
Ponga la información que las personas que usan las funciones necesitan saber en el encabezado.
-
Ponga la información que los mantenedores de las funciones necesitan saber en el código fuente.
Debe usar una herramienta como doxygen, de modo que la documentación se genere mediante comentarios especialmente diseñados en su código fuente.
Me gusta seguir la Guía de estilo de Google C++.
que dice:
Declaraciones de funciones
- Cada declaración de función debe tener comentarios inmediatamente anteriores que describan qué hace la función y cómo usarla. Estos comentarios deben ser descriptivos (“Abre el archivo”) en lugar de imperativos (“Abre el archivo”); el comentario describe la función, no le dice a la función qué hacer. En general, estos comentarios no describen cómo la función realiza su tarea. En cambio, eso debería dejarse para los comentarios en la definición de la función.
Definiciones de funciones
Cada definición de función debe tener un comentario que describa lo que hace la función y cualquier cosa complicada sobre cómo hace su trabajo. Por ejemplo, en el comentario de definición, puede describir los trucos de codificación que usa, brindar una descripción general de los pasos que sigue o explicar por qué eligió implementar la función de la manera que lo hizo en lugar de usar una alternativa viable. Por ejemplo, puede mencionar por qué debe adquirir un bloqueo para la primera mitad de la función pero por qué no es necesario para la segunda mitad.
Tenga en cuenta que no debe simplemente repetir los comentarios proporcionados con la declaración de la función, en el archivo .h o donde sea. Está bien recapitular brevemente lo que hace la función, pero el enfoque de los comentarios debe ser cómo lo hace.
Puntuaciones y comentarios
Agradecemos que quieras sostener nuestro trabajo añadiendo un comentario y dejando una puntuación te damos las gracias.