From 8713da70a3e558c404de4332428787364ffff54e Mon Sep 17 00:00:00 2001 From: Fabio Utzig Date: Wed, 16 Dec 2020 20:22:38 -0300 Subject: [PATCH] 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 --- include/bluetooth/gatt.h | 1 + include/data/json.h | 2 +- include/drivers/kscan.h | 7 +++---- include/drivers/rtc/maxim_ds3231.h | 3 +-- include/drivers/sensor.h | 4 ++-- include/drivers/uart/cdc_acm.h | 3 ++- include/logging/log_output.h | 6 +++--- include/mgmt/mcumgr/smp.h | 4 ++-- include/net/gptp.h | 16 ++++++++-------- include/net/net_context.h | 2 +- include/net/net_if.h | 16 +++++++--------- include/net/net_mgmt.h | 9 ++++----- include/net/websocket.h | 2 +- include/sys/arch_interface.h | 2 +- include/usb/class/usb_audio.h | 1 + 15 files changed, 38 insertions(+), 40 deletions(-) diff --git a/include/bluetooth/gatt.h b/include/bluetooth/gatt.h index f510bf31784..961bb34391c 100644 --- a/include/bluetooth/gatt.h +++ b/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); diff --git a/include/data/json.h b/include/data/json.h index 84ea2eb0c3d..43a5ed27a3f 100644 --- a/include/data/json.h +++ b/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 diff --git a/include/drivers/kscan.h b/include/drivers/kscan.h index f2f2b443311..b08919398ba 100644 --- a/include/drivers/kscan.h +++ b/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, diff --git a/include/drivers/rtc/maxim_ds3231.h b/include/drivers/rtc/maxim_ds3231.h index 68d91bb6b60..b8d0fc9bee2 100644 --- a/include/drivers/rtc/maxim_ds3231.h +++ b/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. */ diff --git a/include/drivers/sensor.h b/include/drivers/sensor.h index 04035f0f63a..b08979f5b8e 100644 --- a/include/drivers/sensor.h +++ b/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); diff --git a/include/drivers/uart/cdc_acm.h b/include/drivers/uart/cdc_acm.h index c306272a70e..c146f90f062 100644 --- a/include/drivers/uart/cdc_acm.h +++ b/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); diff --git a/include/logging/log_output.h b/include/logging/log_output.h index a66c21068a7..96ee14d601a 100644 --- a/include/logging/log_output.h +++ b/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. * diff --git a/include/mgmt/mcumgr/smp.h b/include/mgmt/mcumgr/smp.h index 6dbb66e6afd..1be00106f86 100644 --- a/include/mgmt/mcumgr/smp.h +++ b/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); diff --git a/include/net/gptp.h b/include/net/gptp.h index 6581643b77c..db411add751 100644 --- a/include/net/gptp.h +++ b/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, diff --git a/include/net/net_context.h b/include/net/net_context.h index 3163e20c5c6..5251dd5782a 100644 --- a/include/net/net_context.h +++ b/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 diff --git a/include/net/net_if.h b/include/net/net_if.h index 052c35d9c1b..b52b2b67a7c 100644 --- a/include/net/net_if.h +++ b/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, diff --git a/include/net/net_mgmt.h b/include/net/net_mgmt.h index f07aa74818f..5345f889f48 100644 --- a/include/net/net_mgmt.h +++ b/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, diff --git a/include/net/websocket.h b/include/net/websocket.h index e639238a6aa..bb3f0c5b1c5 100644 --- a/include/net/websocket.h +++ b/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 * diff --git a/include/sys/arch_interface.h b/include/sys/arch_interface.h index c9cc2166411..649596294f4 100644 --- a/include/sys/arch_interface.h +++ b/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); diff --git a/include/usb/class/usb_audio.h b/include/usb/class/usb_audio.h index 3a209a6162b..082ae41558c 100644 --- a/include/usb/class/usb_audio.h +++ b/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.