From 052c4aff53c9fdd1219d9ecc3324d32f794eb624 Mon Sep 17 00:00:00 2001 From: Jim Harris Date: Mon, 18 Jun 2018 07:39:39 -0700 Subject: [PATCH] doc: fix a bunch of parameter-related Doxygen comments There are still a small handful of Doxygen warnings remaining, but this fixes most of what was left. Signed-off-by: Jim Harris Change-Id: I3f8bf3efad2382faf1e6d09f85d802e0ce0bb23d Reviewed-on: https://review.gerrithub.io/415857 Tested-by: SPDK Automated Test System Reviewed-by: Daniel Verkamp Reviewed-by: Ben Walker --- include/spdk/bdev.h | 3 ++- include/spdk/cpuset.h | 2 +- include/spdk/env.h | 2 +- include/spdk/log.h | 2 +- include/spdk/nvme.h | 5 +++-- include/spdk/nvmf.h | 13 ++++++++----- include/spdk/scsi.h | 1 + include/spdk/trace.h | 2 +- include/spdk/uuid.h | 4 ++-- include/spdk/vhost.h | 8 ++++---- 10 files changed, 24 insertions(+), 18 deletions(-) diff --git a/include/spdk/bdev.h b/include/spdk/bdev.h index 4c23d87db..7c17fb9fd 100644 --- a/include/spdk/bdev.h +++ b/include/spdk/bdev.h @@ -858,7 +858,7 @@ int spdk_bdev_nvme_io_passthru(struct spdk_bdev_desc *bdev_desc, * so that portion of the command may be left empty. Also, the namespace * id (nsid) will be populated automatically. * - * \param bdev Block device + * \param bdev_desc Block device descriptor * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel(). * \param cmd The raw NVMe command. Must be in the NVM command set. * \param buf Data buffer to written from. @@ -905,6 +905,7 @@ void spdk_bdev_get_io_stat(struct spdk_bdev *bdev, struct spdk_io_channel *ch, * via the callback function. * * \param bdev Block device to query. + * \param stat Structure for aggregating collected statistics. Passed as argument to cb. * \param cb Called when this operation completes. * \param cb_arg Argument passed to callback function. */ diff --git a/include/spdk/cpuset.h b/include/spdk/cpuset.h index 75bd5755d..d59305714 100644 --- a/include/spdk/cpuset.h +++ b/include/spdk/cpuset.h @@ -138,7 +138,7 @@ uint32_t spdk_cpuset_count(const struct spdk_cpuset *set); /** * Convert a CPU set to hex string. * - * \param CPU set. + * \param set CPU set. * * \return a pointer to hexadecimal representation of CPU set. Buffer to store a * string is dynamically allocated internally and freed with CPU set object. diff --git a/include/spdk/env.h b/include/spdk/env.h index 2b75aa035..57194d37e 100644 --- a/include/spdk/env.h +++ b/include/spdk/env.h @@ -1033,7 +1033,7 @@ int spdk_mem_register(void *vaddr, size_t len); * are completed or cancelled before calling this function. * * \param vaddr Virtual address to unregister. - * \param leng Length in bytes of the vaddr. + * \param len Length in bytes of the vaddr. * * \return 0 on success, negative errno on failure. */ diff --git a/include/spdk/log.h b/include/spdk/log.h index 59eaa70a1..e098dfd18 100644 --- a/include/spdk/log.h +++ b/include/spdk/log.h @@ -144,7 +144,7 @@ int spdk_log_set_trace_flag(const char *flag); /** * Clear a trace flag. * - * \flag Trace flag to clear. + * \param flag Trace flag to clear. * * \return 0 on success, -1 on failure. */ diff --git a/include/spdk/nvme.h b/include/spdk/nvme.h index 10a633af5..06ba4289d 100644 --- a/include/spdk/nvme.h +++ b/include/spdk/nvme.h @@ -886,7 +886,7 @@ int spdk_nvme_ctrlr_cmd_get_feature(struct spdk_nvme_ctrlr *ctrlr, * \param payload_size The size of payload buffer. * \param cb_fn Callback function to invoke when the feature has been retrieved. * \param cb_arg Argument to pass to the callback function. - * \param ns_is The namespace identifier. + * \param ns_id The namespace identifier. * * \return 0 if successfully submitted, ENOMEM if resources could not be allocated * for this request @@ -914,7 +914,7 @@ int spdk_nvme_ctrlr_cmd_get_feature_ns(struct spdk_nvme_ctrlr *ctrlr, uint8_t fe * \param payload_size The size of payload buffer. * \param cb_fn Callback function to invoke when the feature has been set. * \param cb_arg Argument to pass to the callback function. - * \param ns_is The namespace identifier. + * \param ns_id The namespace identifier. * * \return 0 if successfully submitted, ENOMEM if resources could not be allocated * for this request. @@ -1013,6 +1013,7 @@ int spdk_nvme_ctrlr_format(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid, /** * \brief Download a new firmware image. * + * \param ctrlr NVMe controller to perform firmware operation on. * \param payload The data buffer for the firmware image. * \param size The data size will be downloaded. * \param slot The slot that the firmware image will be committed to. diff --git a/include/spdk/nvmf.h b/include/spdk/nvmf.h index a4818541a..9aa290e66 100644 --- a/include/spdk/nvmf.h +++ b/include/spdk/nvmf.h @@ -92,6 +92,8 @@ typedef void (spdk_nvmf_tgt_destroy_done_fn)(void *ctx, int status); * Destroy an NVMe-oF target. * * \param tgt The target to destroy. This releases all resources. + * \param cb_fn A callback that will be called once the target is destroyed + * \param cb_arg A context argument passed to cb_fn. */ void spdk_nvmf_tgt_destroy(struct spdk_nvmf_tgt *tgt, spdk_nvmf_tgt_destroy_done_fn cb_fn, @@ -307,16 +309,17 @@ struct spdk_nvmf_subsystem *spdk_nvmf_tgt_find_subsystem(struct spdk_nvmf_tgt *t * * \param tgt The NVMe-oF target to iterate. * - * \return a pointer to the NVMe-oF subsystem on success, or NULL on failure. + * \return a pointer to the first NVMe-oF subsystem on success, or NULL on failure. */ struct spdk_nvmf_subsystem *spdk_nvmf_subsystem_get_first(struct spdk_nvmf_tgt *tgt); /** * Continue iterating over all known subsystems. If no additional subsystems, return NULL. * - * \param tgt The NVMe-oF target to iterate. + * \param subsystem Previous subsystem returned from \ref spdk_nvmf_subsystem_get_first or + * \ref spdk_nvmf_subsystem_get_next. * - * \return a pointer to the NVMe-oF subsystem on success, or NULL on failure. + * \return a pointer to the next NVMe-oF subsystem on success, or NULL on failure. */ struct spdk_nvmf_subsystem *spdk_nvmf_subsystem_get_next(struct spdk_nvmf_subsystem *subsystem); @@ -326,7 +329,7 @@ struct spdk_nvmf_subsystem *spdk_nvmf_subsystem_get_next(struct spdk_nvmf_subsys * May only be performed on subsystems in the PAUSED or INACTIVE states. * * \param subsystem Subsystem to add host to. - * \param host_nqn The NQN for the host. + * \param hostnqn The NQN for the host. * * \return 0 on success, or negated errno value on failure. */ @@ -339,7 +342,7 @@ int spdk_nvmf_subsystem_add_host(struct spdk_nvmf_subsystem *subsystem, * May only be performed on subsystems in the PAUSED or INACTIVE states. * * \param subsystem Subsystem to remove host from. - * \param host_nqn The NQN for the host. + * \param hostnqn The NQN for the host. * * \return 0 on success, or negated errno value on failure. */ diff --git a/include/spdk/scsi.h b/include/spdk/scsi.h index caa91fff2..2d437dfaf 100644 --- a/include/spdk/scsi.h +++ b/include/spdk/scsi.h @@ -305,6 +305,7 @@ void spdk_scsi_dev_free_io_channels(struct spdk_scsi_dev *dev); * responsible for managing the memory containing this list. lun_id_list[x] is * the LUN ID for lun_list[x]. * \param num_luns Number of entries in lun_list and lun_id_list. + * \param protocol_id SCSI SPC protocol identifier to report in INQUIRY data * \param hotremove_cb Callback to lun hotremoval. Will be called once hotremove * is first triggered. * \param hotremove_ctx Additional argument to hotremove_cb. diff --git a/include/spdk/trace.h b/include/spdk/trace.h index d0f6cb8b7..b897383eb 100644 --- a/include/spdk/trace.h +++ b/include/spdk/trace.h @@ -234,7 +234,7 @@ void spdk_trace_register_object(uint8_t type, char id_prefix); * \param new_object New object for the tpoint. * \param arg1_is_ptr This argument indicates whether argument1 is a pointer. * \param arg1_is_alias This argument indicates whether argument1 is an alias. - * \param agr1_name Name of argument. + * \param arg1_name Name of argument. */ void spdk_trace_register_description(const char *name, const char *short_name, uint16_t tpoint_id, uint8_t owner_type, diff --git a/include/spdk/uuid.h b/include/spdk/uuid.h index 774773d2a..61a58744c 100644 --- a/include/spdk/uuid.h +++ b/include/spdk/uuid.h @@ -58,7 +58,7 @@ SPDK_STATIC_ASSERT(sizeof(struct spdk_uuid) == 16, "Incorrect size"); /** * Convert UUID in textual format into a spdk_uuid. * - * \param uuid[output] User-provided UUID buffer. + * \param[out] uuid User-provided UUID buffer. * \param uuid_str UUID in textual format in C string. * * \return 0 on success, or negative errno on failure. @@ -89,7 +89,7 @@ int spdk_uuid_compare(const struct spdk_uuid *u1, const struct spdk_uuid *u2); /** * Generate a new UUID. * - * \param uuid[out] User-provided UUID buffer to fill. + * \param[out] uuid User-provided UUID buffer to fill. */ void spdk_uuid_generate(struct spdk_uuid *uuid); diff --git a/include/spdk/vhost.h b/include/spdk/vhost.h index b74cc9bef..98ffcebb8 100644 --- a/include/spdk/vhost.h +++ b/include/spdk/vhost.h @@ -134,7 +134,7 @@ const char *spdk_vhost_dev_get_name(struct spdk_vhost_dev *vdev); * Get cpuset of the vhost device. The cpuset is constant throughout the lifetime * of a vdev. It is a subset of SPDK app cpuset vhost was started with. * - * \param dev vhost device. + * \param vdev vhost device. * * \return cpuset of the vdev. */ @@ -188,7 +188,7 @@ void spdk_vhost_get_coalescing(struct spdk_vhost_dev *vdev, uint32_t *delay_base * * \param name name of the vhost device. The name will also be used * for socket name, which is exactly \c socket_base_dir/name - * \param mask string containing cpumask in hex. The leading *0x* + * \param cpumask string containing cpumask in hex. The leading *0x* * is allowed but not required. The mask itself can be constructed as: * ((1 << cpu0) | (1 << cpu1) | ... | (1 << cpuN)). * @@ -268,7 +268,7 @@ int spdk_vhost_scsi_dev_remove_tgt(struct spdk_vhost_dev *vdev, unsigned scsi_tg * * \param name name of the vhost blk device. The name will also be * used for socket name, which is exactly \c socket_base_dir/name - * \param mask string containing cpumask in hex. The leading *0x* + * \param cpumask string containing cpumask in hex. The leading *0x* * is allowed but not required. The mask itself can be constructed as: * ((1 << cpu0) | (1 << cpu1) | ... | (1 << cpuN)). * \param dev_name bdev name to associate with this vhost device @@ -293,7 +293,7 @@ int spdk_vhost_dev_remove(struct spdk_vhost_dev *vdev); * Get underlying SPDK bdev from vhost blk device. The bdev might be NULL, as it * could have been hotremoved. * - * \param ctrl vhost blk device. + * \param ctrlr vhost blk device. * * \return SPDK bdev associated with given vdev. */