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 <james.r.harris@intel.com>
Change-Id: I3f8bf3efad2382faf1e6d09f85d802e0ce0bb23d

Reviewed-on: https://review.gerrithub.io/415857
Tested-by: SPDK Automated Test System <sys_sgsw@intel.com>
Reviewed-by: Daniel Verkamp <daniel.verkamp@intel.com>
Reviewed-by: Ben Walker <benjamin.walker@intel.com>

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.
  */

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.

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.
  */

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.
  */

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.

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.
  */

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.

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,

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);
 

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.
  */