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

【问题标题】：doxygen C pointer to function argument documentationdoxygen C 指向函数参数文档的指针
【发布时间】：2018-12-31 12:23:16
【问题描述】：

我有一个 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 字段内进行，但看起来很尴尬。

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

【问题讨论】：

你不能键入定义函数指针类型并记录它吗？有关示例，请参见 stackoverflow.com/a/30803441。
@Hasturkun 我有很多这样的功能，这样做似乎有点极端。 typedef 只是为了记录......
我认为它可以在一定程度上提高可读性（例如 void (*func) (void *node, void *data) 与 mapFn 作为参数或类似的东西，希望具有描述性的类型名称）。如果您发现自己有一个指向函数的指针接受指向函数的指针等，也会使事情变得不那么模糊。
@Hasturkun 这是个好主意。谢谢！

标签： c function-pointers doxygen

【解决方案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);

struct s_mysql_psi_mutex_v1 中 typedef 的使用：

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

【讨论】：