doc: fix @param usage in callbacks

The proper usage of @param in callbacks is currently unsupported by
Doxygen so not warnings are generated. The issues fixed with this commit
where found while adding support to Doxygen for validating @param in
callbacks like it currently does for functions.

Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>

include/bluetooth/gatt.h

@@ -880,6 +880,7 @@ ssize_t bt_gatt_attr_read_cpf(struct bt_conn *conn,
 /** @brief Notification complete result callback.
  *
  *  @param conn Connection object.
+ *  @param user_data Data passed in by the user.
  */
 typedef void (*bt_gatt_complete_func_t) (struct bt_conn *conn, void *user_data);
 

include/data/json.h

@@ -91,7 +91,7 @@ struct json_obj_descr {
  * encoding JSON data.
  *
  * @param bytes Contents to write to the output
- * @param len Number of bytes in @param bytes to append to output
+ * @param len Number of bytes to append to output
  * @param data User-provided pointer
  *
  * @return This callback function should return a negative number on

include/drivers/kscan.h

@@ -35,10 +35,9 @@ extern "C" {
  * @brief Keyboard scan callback called when user press/release
  * a key on a matrix keyboard.
  *
- * @param dev   Pointer to the device structure for the driver instance.
- * @param data  Data byte passed pack to the user.
- * @param col	Describes column change.
- * @param row	Describes row change.
+ * @param dev Pointer to the device structure for the driver instance.
+ * @param row Describes row change.
+ * @param column Describes column change.
  * @param pressed Describes the kind of key event.
  */
 typedef void (*kscan_callback_t)(const struct device *dev, uint32_t row,

include/drivers/rtc/maxim_ds3231.h

@@ -221,10 +221,9 @@ extern "C" {
  * callback is permitted to invoke operations on the device.
  *
  * @param dev the device from which the callback originated
- *
+ * @param id the alarm id
  * @param syncclock the value from maxim_ds3231_read_syncclock() at the
  * time the alarm interrupt was processed.
- *
  * @param user_data the corresponding parameter from
  * maxim_ds3231_alarm::user_data.
  */

include/drivers/sensor.h

@@ -316,8 +316,8 @@ enum sensor_attribute {
  * @typedef sensor_trigger_handler_t
  * @brief Callback API upon firing of a trigger
  *
- * @param "struct device *dev" Pointer to the sensor device
- * @param "struct sensor_trigger *trigger" The trigger
+ * @param dev Pointer to the sensor device
+ * @param trigger The trigger
  */
 typedef void (*sensor_trigger_handler_t)(const struct device *dev,
 					 struct sensor_trigger *trigger);

include/drivers/uart/cdc_acm.h

@@ -25,7 +25,8 @@ extern "C" {
  * @brief A function that is called when the USB host changes the baud
  * rate.
  *
- * @param port Device struct for the CDC ACM device.
+ * @param dev Device struct for the CDC ACM device.
+ * @param rate New USB baud rate
  */
 typedef void (*cdc_dte_rate_callback_t)(const struct device *dev,
 					uint32_t rate);

include/logging/log_output.h

@@ -53,9 +53,9 @@ extern "C" {
 /**
  * @brief Prototype of the function processing output data.
  *
- * @param data Data.
- * @param length Data length.
- * @param ctx  User context.
+ * @param buf The buffer data.
+ * @param size The buffer size.
+ * @param ctx User context.
  *
  * @return Number of bytes processed, dropped or discarded.
  *

include/mgmt/mcumgr/smp.h

@@ -21,7 +21,7 @@ struct net_buf;
  *
  * The supplied net_buf is always consumed, regardless of return code.
  *
- * @param mst                   The transport to send via.
+ * @param zst                   The transport to send via.
  * @param nb                    The net_buf to transmit.
  *
  * @return                      0 on success, MGMT_ERR_[...] code on failure.
@@ -67,7 +67,7 @@ typedef int zephyr_smp_transport_ud_copy_fn(struct net_buf *dst,
  * connection-specific information in the net_buf user data (e.g., the BLE
  * transport stores the connection reference that has to be decreased).
  *
- * @param nb                    Contains a user_data pointer to be freed.
+ * @param ud                    Contains a user_data pointer to be freed.
  */
 typedef void zephyr_smp_transport_ud_free_fn(void *ud);
 

include/net/gptp.h

@@ -199,14 +199,14 @@ struct gptp_hdr {
  * @typedef gptp_phase_dis_callback_t
  * @brief Define callback that is called after a phase discontinuity has been
  *        sent by the grandmaster.
- * @param "uint8_t *gm_identity" A pointer to first element of a
- *        ClockIdentity array. The size of the array is GPTP_CLOCK_ID_LEN.
- * @param "uint16_t *gm_time_base" A pointer to the value of timeBaseIndicator
- *        of the current grandmaster.
- * @param "struct scaled_ns *last_gm_ph_change" A pointer to the value of
- *        lastGmPhaseChange received from grandmaster.
- * @param "double *last_gm_freq_change" A pointer to the value of
- *        lastGmFreqChange received from the grandmaster.
+ * @param gm_identity A pointer to first element of a ClockIdentity array.
+ *        The size of the array is GPTP_CLOCK_ID_LEN.
+ * @param time_base A pointer to the value of timeBaseIndicator of the current
+ *        grandmaster.
+ * @param last_gm_ph_change A pointer to the value of lastGmPhaseChange received
+ *        from grandmaster.
+ * @param last_gm_freq_change A pointer to the value of lastGmFreqChange
+ *        received from the grandmaster.
  */
 typedef void (*gptp_phase_dis_callback_t)(
 	uint8_t *gm_identity,

include/net/net_context.h

@@ -121,7 +121,7 @@ typedef void (*net_context_send_cb_t)(struct net_context *context,
  * context is used here. Keep processing in the callback minimal to reduce the
  * time spent blocked while handling packets.
  *
- * @param context The context to use.
+ * @param new_context The context to use.
  * @param addr The peer address.
  * @param addrlen Length of the peer address.
  * @param status The status code, 0 on success, < 0 otherwise

include/net/net_if.h

@@ -999,10 +999,10 @@ struct net_if_mcast_addr *net_if_ipv6_maddr_lookup(const struct in6_addr *addr,
  * @brief Define callback that is called whenever IPv6 multicast address group
  * is joined or left.
 
- * @param "struct net_if *iface" A pointer to a struct net_if to which the
- *        multicast address is attached.
- * @param "const struct in6_addr *addr" IPv6 multicast address.
- * @param "bool is_joined" True if the address is joined, false if left.
+ * @param iface A pointer to a struct net_if to which the multicast address is
+ *        attached.
+ * @param addr IPv6 multicast address.
+ * @param is_joined True if the address is joined, false if left.
  */
 typedef void (*net_if_mcast_callback_t)(struct net_if *iface,
 					const struct in6_addr *addr,
@@ -1855,11 +1855,9 @@ struct net_if *net_if_select_src_iface(const struct sockaddr *dst);
  * @typedef net_if_link_callback_t
  * @brief Define callback that is called after a network packet
  *        has been sent.
- * @param "struct net_if *iface" A pointer to a struct net_if to which the
- *        the net_pkt was sent to.
- * @param "struct net_linkaddr *dst" Link layer address of the destination
- *        where the network packet was sent.
- * @param "int status" Send status, 0 is ok, < 0 error.
+ * @param iface A pointer to a struct net_if to which the the net_pkt was sent to.
+ * @param dst Link layer address of the destination where the network packet was sent.
+ * @param status Send status, 0 is ok, < 0 error.
  */
 typedef void (*net_if_link_callback_t)(struct net_if *iface,
 				       struct net_linkaddr *dst,

include/net/net_mgmt.h

@@ -105,11 +105,10 @@ struct net_mgmt_event_callback;
 /**
  * @typedef net_mgmt_event_handler_t
  * @brief Define the user's callback handler function signature
- * @param "struct net_mgmt_event_callback *cb"
- *        Original struct net_mgmt_event_callback owning this handler.
- * @param "uint32_t mgmt_event" The network event being notified.
- * @param "struct net_if *iface" A pointer on a struct net_if to which the
- *        the event belongs to, if it's an event on an iface. NULL otherwise.
+ * @param cb Original struct net_mgmt_event_callback owning this handler.
+ * @param mgmt_event The network event being notified.
+ * @param iface A pointer on a struct net_if to which the the event belongs to,
+ *        if it's an event on an iface. NULL otherwise.
  */
 typedef void (*net_mgmt_event_handler_t)(struct net_mgmt_event_callback *cb,
 					 uint32_t mgmt_event,

include/net/websocket.h

@@ -51,7 +51,7 @@ enum websocket_opcode  {
  * @typedef websocket_connect_cb_t
  * @brief Callback called after Websocket connection is established.
  *
- * @param sock Websocket id
+ * @param ws_sock Websocket id
  * @param req HTTP handshake request
  * @param user_data A valid pointer on some user data or NULL
  *

include/sys/arch_interface.h

@@ -190,7 +190,7 @@ void arch_cpu_atomic_idle(unsigned int key);
 /**
  * Per-cpu entry function
  *
- * @param context parameter, implementation specific
+ * @param data context parameter, implementation specific
  */
 typedef FUNC_NORETURN void (*arch_cpustart_t)(void *data);
 

include/usb/class/usb_audio.h

@@ -195,6 +195,7 @@ typedef void (*usb_audio_data_completion_cb_t)(const struct device *dev,
  *
  * @warning Host may not use all of configured features.
  *
+ * @param dev USB Audio device
  * @param evt Pointer to an event to be parsed by the App.
  *	      Pointer sturct is temporary and is valid only during the
  *	      execution of this callback.