[dpdk-dev] [PATCH v2] crypto/scheduler: fix Doxygen comments

[De Lara Guarch, Pablo]

Hi Fan,

> -----Original Message-----
> From: dev [mailto:dev-bounces at dpdk.org] On Behalf Of Fan Zhang
> Sent: Wednesday, April 12, 2017 3:11 PM
> To: dev at dpdk.org
> Cc: De Lara Guarch, Pablo; stable at dpdk.org; Mcnamara, John
> Subject: [dpdk-dev] [PATCH v2] crypto/scheduler: fix Doxygen comments
> 
> 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 at intel.com>
> ---
> 

...

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

Remove "<" before this macro: /** Maximum number... */).

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

Start with capital letters (same for other comments in the file)

...

>  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

SHALL -> will

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

The description has to go after the variable, not before.

>  	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