En los idiomas que distinguen entre un archivo "fuente" y un "encabezado" (principalmente C y C ++), es mejor documentar las funciones en el archivo del encabezado:
(extraído de CCAN )
/**
* time_now - return the current time
*
* Example:
* printf("Now is %lu seconds since epoch\n", (long)time_now().tv_sec);
*/
struct timeval time_now(void);
o en el archivo fuente?
(extraído de PostgreSQL)
/*
* Convert a UTF-8 character to a Unicode code point.
* This is a one-character version of pg_utf2wchar_with_len.
*
* No error checks here, c must point to a long-enough string.
*/
pg_wchar
utf8_to_unicode(const unsigned char *c)
{
...
Tenga en cuenta que algunas cosas se definen solo en el encabezado, como las funciones structs, macros y static inline . Solo estoy hablando de cosas que están declaradas en un archivo de encabezado y definidas en un archivo fuente.
Aquí hay algunos argumentos que se me ocurren. Me inclino por documentar en el archivo de origen, por lo que mis argumentos de "Pro-header" pueden ser un tanto débiles.
Pro-header:
- El usuario no necesita el código fuente para ver la documentación.
- La fuente puede ser inconveniente, o incluso imposible, de adquirir.
- Esto mantiene la interfaz y la implementación aún más separadas.
Pro-source:
- Hace que el encabezado sea mucho más corto, lo que brinda al lector una visión general del módulo en su conjunto.
- Empareja la documentación de una función con su implementación, lo que facilita ver que una función hace lo que dice que hace.
Al responder, tenga cuidado con los argumentos basados en lo que pueden hacer las herramientas y los "IDE modernos". Ejemplos:
- Pro-header: el plegado de código puede ayudar a hacer que los encabezados comentados sean más navegables ocultando los comentarios.
- Pro-source: la función
Find this global definitionde cscope lo lleva al archivo de origen (donde la definición is) en lugar del archivo de encabezado (donde está la declaración )
No estoy diciendo que no hagas esos argumentos, pero ten en cuenta que no todos se sienten tan cómodos con las herramientas que usas como tú.