На языках, которые различают исходный файл и файл заголовка (в основном C и C ++), лучше документировать функции в заголовочном файле:
(ворованный из 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);
или в исходном файле?
(украдено из 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)
{
...
Обратите внимание, что некоторые вещи определены только в заголовке, например структуры, макросы и static inlineфункции. Я говорю только о вещах, которые объявлены в заголовочном файле и определены в исходном файле.
Вот некоторые аргументы, которые я могу придумать. Я склоняюсь к документированию в исходном файле, поэтому мои аргументы «Pro-header» могут быть несколько слабыми.
Pro-заголовок:
- Пользователю не нужен исходный код для просмотра документации.
- Источник может быть неудобным или даже невозможным для приобретения.
- Это держит интерфейс и реализацию дальше друг от друга.
Pro-источник:
- Это делает заголовок намного короче, предоставляя читателю обзор модуля в целом.
- Он сопрягает документацию функции с ее реализацией, облегчая понимание того, что функция делает то, что говорит.
При ответе, пожалуйста, будьте осторожны с аргументами, основанными на том, что могут сделать инструменты и «современные IDE». Примеры:
- Pro-header: свертывание кода может помочь сделать заголовки с комментариями более удобными, скрывая комментарии.
- Pro-источник: Cscope «s
Find this global definitionфункция принимает вас к исходному файлу (где определение является) , а не файл заголовка (где декларация является).
Я не говорю, что не приводите таких аргументов, но имейте в виду, что не всем так удобно пользоваться инструментами, которыми вы пользуетесь.