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的指针的值。可以在@param func字段中执行此操作，但似乎很尴尬。

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

Answer 1

As @Hasturkun pointed out, the solution is to use a typedef.

See for example how this is done in MySQL, which uses a lot of function pointers in structures:

Typedef definition of 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);

Use of the typedef in 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;

Resulting doxygen doc:

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

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

1 个答案: