doxygen C pointer to function argument documentation

user_5745120 0
Viewed 977

I have a C function that takes pointer to a function as an argument. This function argument is supposed to be supplied by a library user so it is not implemented in source files.

/** @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);

I'm writing documentation to it using doxygen and I'm not sure how to document arguments and return values of the pointer to a function argument func. It's possible to do it inside @param func field but it seems awkward.

What is the best way to document arguments and return values of the pointer to the function func using doxygen? Is it possible to create a nested function documentation for func inside map or to create a dummy function documentation that can be referenced?

function-pointers doxygen c
1 Answers

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

user_11575400
Related