[PATCH v2] crypto/scheduler: fix Doxygen comments

[Fan Zhang <roy.fan.zhang@intel.com>]

This patch adds the missing doxygen comments and updated
inline comments to cryptodev scheduler

Fixes: d58a3f312545 ("crypto/scheduler: add documentation")

Signed-off-by: Fan Zhang <roy.fan.zhang@intel.com>
---

v2:
- fixed typo

 doc/api/doxy-api-index.md                          |   3 +-
 doc/api/doxy-api.conf                              |   1 +
 drivers/crypto/scheduler/rte_cryptodev_scheduler.h | 133 ++++++++++++++-------
 3 files changed, 94 insertions(+), 43 deletions(-)

diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md
index a26846a..f5f1f19 100644
--- a/doc/api/doxy-api-index.md
+++ b/doc/api/doxy-api-index.md
@@ -51,7 +51,8 @@ There are many libraries, so their headers may be grouped by topics:
   [vhost]              (@ref rte_vhost.h),
   [KNI]                (@ref rte_kni.h),
   [ixgbe]              (@ref rte_pmd_ixgbe.h),
-  [i40e]               (@ref rte_pmd_i40e.h)
+  [i40e]               (@ref rte_pmd_i40e.h),
+  [crypto_scheduler]   (@ref rte_cryptodev_scheduler.h)
 
 - **memory**:
   [memseg]             (@ref rte_memory.h),
diff --git a/doc/api/doxy-api.conf b/doc/api/doxy-api.conf
index 97fb551..ca9194f 100644
--- a/doc/api/doxy-api.conf
+++ b/doc/api/doxy-api.conf
@@ -30,6 +30,7 @@
 
 PROJECT_NAME            = DPDK
 INPUT                   = doc/api/doxy-api-index.md \
+                          drivers/crypto/scheduler \
                           drivers/net/bonding \
                           drivers/net/i40e \
                           drivers/net/ixgbe \
diff --git a/drivers/crypto/scheduler/rte_cryptodev_scheduler.h b/drivers/crypto/scheduler/rte_cryptodev_scheduler.h
index 3b816d3..89d0b9c 100644
--- a/drivers/crypto/scheduler/rte_cryptodev_scheduler.h
+++ b/drivers/crypto/scheduler/rte_cryptodev_scheduler.h
@@ -34,6 +34,18 @@
 #ifndef _RTE_CRYPTO_SCHEDULER_H
 #define _RTE_CRYPTO_SCHEDULER_H
 
+/**
+ * @file rte_cryptodev_scheduler.h
+ *
+ * RTE Cryptodev Scheduler Device
+ *
+ * The RTE Cryptodev Scheduler Device allows the aggregation of multiple (slave)
+ * Cryptodevs into a single logical crypto device, and the scheduling the
+ * crypto operations to the slaves based on the mode of the specified mode of
+ * operation specified and supported. This implementation supports 3 modes of
+ * operation: round robin, packet-size based, and fail-over.
+ */
+
 #include "rte_cryptodev_scheduler_operations.h"
 
 #ifdef __cplusplus
@@ -45,19 +57,21 @@ extern "C" {
 #define RTE_CRYPTODEV_SCHEDULER_MAX_NB_SLAVES	(8)
 #endif
 
-/* round-robin scheduling mode */
+/** round-robin scheduling mode string */
 #define SCHEDULER_MODE_NAME_ROUND_ROBIN		round-robin
-/* packet-size based distribution scheduling mode */
+/** packet-size based distribution scheduling mode string */
 #define SCHEDULER_MODE_NAME_PKT_SIZE_DISTR	packet-size-distr
-/* fail-over mode */
+/** fail-over scheduling mode string */
 #define SCHEDULER_MODE_NAME_FAIL_OVER		fail-over
-/**
 
+/**
  * Crypto scheduler PMD operation modes
  */
 enum rte_cryptodev_scheduler_mode {
 	CDEV_SCHED_MODE_NOT_SET = 0,
+	/** user defined mode */
 	CDEV_SCHED_MODE_USERDEFINED,
+	/** round-robin mode */
 	CDEV_SCHED_MODE_ROUNDROBIN,
 	/** packet-size based distribution mode */
 	CDEV_SCHED_MODE_PKT_SIZE_DISTR,
@@ -75,36 +89,49 @@ struct rte_cryptodev_scheduler;
 /**
  * Load a user defined scheduler
  *
- * @param	scheduler_id	The target scheduler device ID
- *		scheduler	Pointer to the user defined scheduler
+ * @param scheduler_id
+ *   The target scheduler device ID
+ * @param scheduler
+ *   Pointer to the user defined scheduler
  *
  * @return
- *	0 if loading successful, negative integer if otherwise.
+ *   - 0 if the scheduler is successfully loaded
+ *   - -ENOTSUP if the operation is not supported.
+ *   - -EBUSY if device is started.
  */
 int
 rte_cryptodev_scheduler_load_user_scheduler(uint8_t scheduler_id,
 		struct rte_cryptodev_scheduler *scheduler);
 
 /**
- * Attach a pre-configured crypto device to the scheduler
+ * Attach a crypto device to the scheduler
  *
- * @param	scheduler_id	The target scheduler device ID
- *		slave_id	crypto device ID to be attached
+ * @param scheduler_id
+ *   The target scheduler device ID
+ * @param slave_id
+ *   crypto device ID to be attached
  *
  * @return
- *	0 if attaching successful, negative int if otherwise.
+ *   - 0 if the slave is attached.
+ *   - -ENOTSUP if the operation is not supported.
+ *   - -EBUSY if device is started.
+ *   - -ENOMEM if the scheduler's slave list is full.
  */
 int
 rte_cryptodev_scheduler_slave_attach(uint8_t scheduler_id, uint8_t slave_id);
 
 /**
- * Detach a attached crypto device to the scheduler
+ * Detach a crypto device from the scheduler
  *
- * @param	scheduler_id	The target scheduler device ID
- *		slave_id	crypto device ID to be detached
+ * @param scheduler_id
+ *   The target scheduler device ID
+ * @param slave_id
+ *   crypto device ID to be detached
  *
  * @return
- *	0 if detaching successful, negative int if otherwise.
+ *   - 0 if the slave is detached.
+ *   - -ENOTSUP if the operation is not supported.
+ *   - -EBUSY if device is started.
  */
 int
 rte_cryptodev_scheduler_slave_detach(uint8_t scheduler_id, uint8_t slave_id);
@@ -113,11 +140,15 @@ rte_cryptodev_scheduler_slave_detach(uint8_t scheduler_id, uint8_t slave_id);
 /**
  * Set the scheduling mode
  *
- * @param	scheduler_id	The target scheduler device ID
- *		mode		The scheduling mode
+ * @param scheduler_id
+ *   The target scheduler device ID
+ * @param mode
+ *   The scheduling mode
  *
  * @return
- *	0 if attaching successful, negative integer if otherwise.
+ *   - 0 if the mode is set.
+ *   - -ENOTSUP if the operation is not supported.
+ *   - -EBUSY if device is started.
  */
 int
 rte_cryptodev_scheduler_mode_set(uint8_t scheduler_id,
@@ -126,8 +157,12 @@ rte_cryptodev_scheduler_mode_set(uint8_t scheduler_id,
 /**
  * Get the current scheduling mode
  *
- * @param	scheduler_id	The target scheduler device ID
- *		mode		Pointer to write the scheduling mode
+ * @param scheduler_id
+ *   The target scheduler device ID
+ *
+ * @return mode
+ *   - non-negative enumerate value: the scheduling mode
+ *   - -ENOTSUP if the operation is not supported.
  */
 enum rte_cryptodev_scheduler_mode
 rte_cryptodev_scheduler_mode_get(uint8_t scheduler_id);
@@ -136,8 +171,10 @@ rte_cryptodev_scheduler_mode_get(uint8_t scheduler_id);
  * @deprecated
  * Set the scheduling mode
  *
- * @param	scheduler_id	The target scheduler device ID
- *		mode		The scheduling mode
+ * @param scheduler_id
+ *   The target scheduler device ID
+ * @param mode
+ *   The scheduling mode
  *
  * @return
  *	0 if attaching successful, negative integer if otherwise.
@@ -151,8 +188,12 @@ rte_crpytodev_scheduler_mode_set(uint8_t scheduler_id,
  * @deprecated
  * Get the current scheduling mode
  *
- * @param	scheduler_id	The target scheduler device ID
- *		mode		Pointer to write the scheduling mode
+ * @param scheduler_id
+ *   The target scheduler device ID
+ *
+ * @return
+ *	If successful, returns the scheduling mode, negative integer
+ *	otherwise
  */
 __rte_deprecated
 enum rte_cryptodev_scheduler_mode
@@ -161,13 +202,17 @@ rte_crpytodev_scheduler_mode_get(uint8_t scheduler_id);
 /**
  * Set the crypto ops reordering feature on/off
  *
- * @param	dev_id		The target scheduler device ID
- *		enable_reorder	set the crypto op reordering feature
- *				0: disable reordering
- *				1: enable reordering
+ * @param scheduler_id
+ *   The target scheduler device ID
+ * @param enable_reorder
+ *   Set the crypto op reordering feature
+ *   - 0: disable reordering
+ *   - 1: enable reordering
  *
  * @return
- *	0 if setting successful, negative integer if otherwise.
+ *   - 0 if the ordering is set.
+ *   - -ENOTSUP if the operation is not supported.
+ *   - -EBUSY if device is started.
  */
 int
 rte_cryptodev_scheduler_ordering_set(uint8_t scheduler_id,
@@ -176,12 +221,13 @@ rte_cryptodev_scheduler_ordering_set(uint8_t scheduler_id,
 /**
  * Get the current crypto ops reordering feature
  *
- * @param	dev_id		The target scheduler device ID
+ * @param scheduler_id
+ *   The target scheduler device ID
  *
  * @return
- *	0 if reordering is disabled
- *	1 if reordering is enabled
- *	negative integer if otherwise.
+ *   - 0 if reordering is disabled
+ *   - 1 if reordering is enabled
+ *   - -ENOTSUP if the operation is not supported.
  */
 int
 rte_cryptodev_scheduler_ordering_get(uint8_t scheduler_id);
@@ -192,15 +238,13 @@ rte_cryptodev_scheduler_ordering_get(uint8_t scheduler_id);
  * @param scheduler_id
  *   The target scheduler device ID
  * @param slaves
- *  If successful, the function will write back
- *  all slaves' device IDs to it. This
- *  parameter SHALL either be an uint8_t array
- *  of RTE_CRYPTODEV_SCHEDULER_MAX_NB_SLAVES
- *  elements or NULL.
+ *   If successful, the function will write back all slaves' device IDs to it.
+ *   This parameter SHALL either be an uint8_t array of
+ *   RTE_CRYPTODEV_SCHEDULER_MAX_NB_SLAVES elements or NULL.
  *
  * @return
  *   - non-negative number: the number of slaves attached
- *   - negative integer if error occurs.
+ *   - -ENOTSUP if the operation is not supported.
  */
 int
 rte_cryptodev_scheduler_slaves_get(uint8_t scheduler_id, uint8_t *slaves);
@@ -211,16 +255,21 @@ typedef uint16_t (*rte_cryptodev_scheduler_burst_enqueue_t)(void *qp_ctx,
 typedef uint16_t (*rte_cryptodev_scheduler_burst_dequeue_t)(void *qp_ctx,
 		struct rte_crypto_op **ops, uint16_t nb_ops);
 
+/** The data structure associated with each mode of scheduler. */
 struct rte_cryptodev_scheduler {
-	const char *name;
-	const char *description;
-	enum rte_cryptodev_scheduler_mode mode;
+	const char *name;                        /**< scheduler name */
+	const char *description;                 /**< scheduler description */
+	enum rte_cryptodev_scheduler_mode mode;  /**< scheduling mode */
 
+	/**< pointer to scheduler operation structure */
 	struct rte_cryptodev_scheduler_ops *ops;
 };
 
+/** round-robin mode scheduler */
 extern struct rte_cryptodev_scheduler *roundrobin_scheduler;
+/** packet-size based distribution mode scheduler */
 extern struct rte_cryptodev_scheduler *pkt_size_based_distr_scheduler;
+/** fail-over mode scheduler */
 extern struct rte_cryptodev_scheduler *failover_scheduler;
 
 #ifdef __cplusplus
-- 
2.7.4