指向函数参数文档的 doxygen C 指针

Question

我有一个 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 的指针的 return 值。可以在 @param func 字段中进行，但看起来很尴尬。

使用 doxygen 记录参数和指向函数 func 的指针的 return 值的最佳方法是什么？是否可以在 map 中为 func 创建一个嵌套函数文档或创建一个可以引用的虚拟函数文档？

Answer 1

正如@Hasturkun 指出的那样，解决方案是使用 typedef。

参见 MySQL 中的示例，它在结构中使用了大量函数指针：

start_mutex_wait_v1_t 的 Typedef 定义：

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 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 文档：

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

指向函数参数文档的 doxygen C 指针

doxygen C pointer to function argument documentation

c

doxygen

function-pointers