указатель doxygen C на документацию аргумента функции - PullRequest
Новая
       12

указатель doxygen C на документацию аргумента функции

0 голосов
/ 31 декабря 2018

У меня есть функция C, которая принимает указатель на функцию в качестве аргумента.Предполагается, что этот аргумент функции предоставлен пользователем библиотеки, поэтому он не реализован в исходных файлах. 

/** @brief Map function.
 *
 * Apply function to each node of list.
 *
 * @relates list
 * @param[in] self list handle.
 * @param[in] func function to apply to list nodes.
 * @param[in] data user data passed to function.
 */
void map(struct list *self,
         void (*func) (void *node, void *data),
         void *data);

Я пишу в него документацию, используя doxygen , и я незнать, как документировать аргументы и возвращать значения указателя на аргумент функции func.Это можно сделать в поле @param func, но это кажется неудобным.

Каков наилучший способ документировать аргументы и возвращать значения указателя на функцию func с помощью doxygen?Можно ли создать документацию для вложенных функций для func внутри map или создать фиктивную документацию по функциям, на которую можно ссылаться?

1 Ответ

0 голосов
/ 07 января 2019

Как отметил @Hasturkun, решение состоит в том, чтобы использовать typedef.

Посмотрите, например, как это делается в MySQL, которая использует множество указателей на функции в структурах:

Typedefопределение start_mutex_wait_v1_t:

https://github.com/mysql/mysql-server/blob/8.0/include/mysql/components/services/psi_mutex_bits.h#L179

/**
  Record a mutex instrumentation wait start event.
  @param state data storage for the locker
  @param mutex the instrumented mutex to lock
  @param op the operation to perform
  @param src_file the source file name
  @param src_line the source line number
  @return a mutex locker, or NULL
*/
typedef struct PSI_mutex_locker *(*start_mutex_wait_v1_t)(
    struct PSI_mutex_locker_state_v1 *state, struct PSI_mutex *mutex,
enum PSI_mutex_operation op, const char *src_file, unsigned int src_line);

Использование typedef в struct s_mysql_psi_mutex_v1:

https://github.com/mysql/mysql-server/blob/8.0/include/mysql/components/services/psi_mutex_service.h#L37

start_mutex_wait_v1_t start_mutex_wait;

Результирующий doxygen doc:

https://dev.mysql.com/doc/dev/mysql-server/latest/structs__mysql__psi__mutex__v1.html

...