[dpdk-dev] [PATCH] security: update doxygen fields

[dpdk-dev] [PATCH] security: update doxygen fields

[Radu Nicolau]

Replace /**< with /** for multiline doxygen comments.

Signed-off-by: Radu Nicolau <radu.nicolau@intel.com>
---
 lib/librte_security/rte_security.h | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/lib/librte_security/rte_security.h b/lib/librte_security/rte_security.h
index 96806e3..d56907d 100644
--- a/lib/librte_security/rte_security.h
+++ b/lib/librte_security/rte_security.h
@@ -115,14 +115,14 @@ struct rte_security_ipsec_tunnel_param {
  * IPsec Security Association option flags
  */
 struct rte_security_ipsec_sa_options {
-	/**< Extended Sequence Numbers (ESN)
+	/** Extended Sequence Numbers (ESN)
 	 *
 	 * * 1: Use extended (64 bit) sequence numbers
 	 * * 0: Use normal sequence numbers
 	 */
 	uint32_t esn : 1;
 
-	/**< UDP encapsulation
+	/** UDP encapsulation
 	 *
 	 * * 1: Do UDP encapsulation/decapsulation so that IPSEC packets can
 	 *      traverse through NAT boxes.
@@ -130,7 +130,7 @@ struct rte_security_ipsec_sa_options {
 	 */
 	uint32_t udp_encap : 1;
 
-	/**< Copy DSCP bits
+	/** Copy DSCP bits
 	 *
 	 * * 1: Copy IPv4 or IPv6 DSCP bits from inner IP header to
 	 *      the outer IP header in encapsulation, and vice versa in
@@ -139,7 +139,7 @@ struct rte_security_ipsec_sa_options {
 	 */
 	uint32_t copy_dscp : 1;
 
-	/**< Copy IPv6 Flow Label
+	/** Copy IPv6 Flow Label
 	 *
 	 * * 1: Copy IPv6 flow label from inner IPv6 header to the
 	 *      outer IPv6 header.
@@ -147,7 +147,7 @@ struct rte_security_ipsec_sa_options {
 	 */
 	uint32_t copy_flabel : 1;
 
-	/**< Copy IPv4 Don't Fragment bit
+	/** Copy IPv4 Don't Fragment bit
 	 *
 	 * * 1: Copy the DF bit from the inner IPv4 header to the outer
 	 *      IPv4 header.
@@ -155,7 +155,7 @@ struct rte_security_ipsec_sa_options {
 	 */
 	uint32_t copy_df : 1;
 
-	/**< Decrement inner packet Time To Live (TTL) field
+	/** Decrement inner packet Time To Live (TTL) field
 	 *
 	 * * 1: In tunnel mode, decrement inner packet IPv4 TTL or
 	 *      IPv6 Hop Limit after tunnel decapsulation, or before tunnel
@@ -164,7 +164,7 @@ struct rte_security_ipsec_sa_options {
 	 */
 	uint32_t dec_ttl : 1;
 
-	/**< Explicit Congestion Notification (ECN)
+	/** Explicit Congestion Notification (ECN)
 	 *
 	 * * 1: In tunnel mode, enable outer header ECN Field copied from
 	 *      inner header in tunnel encapsulation, or inner header ECN
-- 
2.7.4

Re: [dpdk-dev] [EXT] [PATCH] security: update doxygen fields

[Anoob Joseph]

Hi Radu,

Most parts of the file(rte_security.h) follows 'description after item' methodology. Do you think we should stick to that?

@Akhil, @Thomas, what is the recommended way of documenting individual members of structure? Is it 'description after the item' or 'description before the item'?

Thanks,
Anoob

> -----Original Message-----
> From: Radu Nicolau <radu.nicolau@intel.com>
> Sent: Tuesday, September 3, 2019 6:28 PM
> To: dev@dpdk.org
> Cc: akhil.goyal@nxp.com; konstantin.ananyev@intel.com;
> bernard.iremonger@intel.com; declan.doherty@intel.com;
> stephen@networkplumber.org; Anoob Joseph <anoobj@marvell.com>;
> Radu Nicolau <radu.nicolau@intel.com>
> Subject: [EXT] [PATCH] security: update doxygen fields
> 
> External Email
> 
> ----------------------------------------------------------------------
> Replace /**< with /** for multiline doxygen comments.
> 
> Signed-off-by: Radu Nicolau <radu.nicolau@intel.com>
> ---
>  lib/librte_security/rte_security.h | 14 +++++++-------
>  1 file changed, 7 insertions(+), 7 deletions(-)
> 
> diff --git a/lib/librte_security/rte_security.h
> b/lib/librte_security/rte_security.h
> index 96806e3..d56907d 100644
> --- a/lib/librte_security/rte_security.h
> +++ b/lib/librte_security/rte_security.h
> @@ -115,14 +115,14 @@ struct rte_security_ipsec_tunnel_param {
>   * IPsec Security Association option flags
>   */
>  struct rte_security_ipsec_sa_options {
> -	/**< Extended Sequence Numbers (ESN)
> +	/** Extended Sequence Numbers (ESN)
>  	 *
>  	 * * 1: Use extended (64 bit) sequence numbers
>  	 * * 0: Use normal sequence numbers
>  	 */
>  	uint32_t esn : 1;
> 
> -	/**< UDP encapsulation
> +	/** UDP encapsulation
>  	 *
>  	 * * 1: Do UDP encapsulation/decapsulation so that IPSEC packets can
>  	 *      traverse through NAT boxes.
> @@ -130,7 +130,7 @@ struct rte_security_ipsec_sa_options {
>  	 */
>  	uint32_t udp_encap : 1;
> 
> -	/**< Copy DSCP bits
> +	/** Copy DSCP bits
>  	 *
>  	 * * 1: Copy IPv4 or IPv6 DSCP bits from inner IP header to
>  	 *      the outer IP header in encapsulation, and vice versa in
> @@ -139,7 +139,7 @@ struct rte_security_ipsec_sa_options {
>  	 */
>  	uint32_t copy_dscp : 1;
> 
> -	/**< Copy IPv6 Flow Label
> +	/** Copy IPv6 Flow Label
>  	 *
>  	 * * 1: Copy IPv6 flow label from inner IPv6 header to the
>  	 *      outer IPv6 header.
> @@ -147,7 +147,7 @@ struct rte_security_ipsec_sa_options {
>  	 */
>  	uint32_t copy_flabel : 1;
> 
> -	/**< Copy IPv4 Don't Fragment bit
> +	/** Copy IPv4 Don't Fragment bit
>  	 *
>  	 * * 1: Copy the DF bit from the inner IPv4 header to the outer
>  	 *      IPv4 header.
> @@ -155,7 +155,7 @@ struct rte_security_ipsec_sa_options {
>  	 */
>  	uint32_t copy_df : 1;
> 
> -	/**< Decrement inner packet Time To Live (TTL) field
> +	/** Decrement inner packet Time To Live (TTL) field
>  	 *
>  	 * * 1: In tunnel mode, decrement inner packet IPv4 TTL or
>  	 *      IPv6 Hop Limit after tunnel decapsulation, or before tunnel
> @@ -164,7 +164,7 @@ struct rte_security_ipsec_sa_options {
>  	 */
>  	uint32_t dec_ttl : 1;
> 
> -	/**< Explicit Congestion Notification (ECN)
> +	/** Explicit Congestion Notification (ECN)
>  	 *
>  	 * * 1: In tunnel mode, enable outer header ECN Field copied from
>  	 *      inner header in tunnel encapsulation, or inner header ECN
> --
> 2.7.4

Re: [dpdk-dev] [EXT] [PATCH] security: update doxygen fields

[Thomas Monjalon]

04/09/2019 05:41, Anoob Joseph:
> Hi Radu,
> 
> Most parts of the file(rte_security.h) follows 'description after item' methodology. Do you think we should stick to that?
> 
> @Akhil, @Thomas, what is the recommended way of documenting individual members of structure? Is it 'description after the item' or 'description before the item'?

In general, it is better to have the description before.
The description "after" is preferred for short descriptions
of struct items which fit on the same line with the item.

Re: [dpdk-dev] [PATCH] security: update doxygen fields

[Akhil Goyal]

> 
> Replace /**< with /** for multiline doxygen comments.
> 
> Signed-off-by: Radu Nicolau <radu.nicolau@intel.com>
This is a bug in the doxygen build, better to have a fixes line here and cc to stable.

Acked-by: Akhil Goyal <akhil.goyal@nxp.com>

Re: [dpdk-dev] [EXT] [PATCH] security: update doxygen fields

[Akhil Goyal]

> 
> Hi Radu,
> 
> Most parts of the file(rte_security.h) follows 'description after item'
> methodology. Do you think we should stick to that?
> 
> @Akhil, @Thomas, what is the recommended way of documenting individual
> members of structure? Is it 'description after the item' or 'description before the
> item'?
> 

Recommended way is as suggested by Thomas(in other email) and that can be done separately.
However it is not a documentation bug but this patch resolves a bug in the documentation
which should be backported as well.

-Akhil

Re: [dpdk-dev] [EXT] [PATCH] security: update doxygen fields

[Anoob Joseph]

> -----Original Message-----
> From: Radu Nicolau <radu.nicolau@intel.com>
> Sent: Tuesday, September 3, 2019 6:28 PM
> To: dev@dpdk.org
> Cc: akhil.goyal@nxp.com; konstantin.ananyev@intel.com;
> bernard.iremonger@intel.com; declan.doherty@intel.com;
> stephen@networkplumber.org; Anoob Joseph <anoobj@marvell.com>;
> Radu Nicolau <radu.nicolau@intel.com>
> Subject: [EXT] [PATCH] security: update doxygen fields
> 
> External Email
> 
> ----------------------------------------------------------------------
> Replace /**< with /** for multiline doxygen comments.
> 
> Signed-off-by: Radu Nicolau <radu.nicolau@intel.com>

Acked-by: Anoob Joseph <anoobj@marvell.com>

[dpdk-dev] [PATCH v2] security: update doxygen fields

[Radu Nicolau]

Replace /**< with /** for multiline doxygen comments.

Fixes: c261d1431bd8 ("security: introduce security API and framework")
Cc: stable@dpdk.org

Signed-off-by: Radu Nicolau <radu.nicolau@intel.com>
Acked-by: Akhil Goyal <akhil.goyal@nxp.com>
Acked-by: Anoob Joseph <anoobj@marvell.com>
---
v2: add fixes line and CC'ed stable

 lib/librte_security/rte_security.h | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/lib/librte_security/rte_security.h b/lib/librte_security/rte_security.h
index 96806e3..d56907d 100644
--- a/lib/librte_security/rte_security.h
+++ b/lib/librte_security/rte_security.h
@@ -115,14 +115,14 @@ struct rte_security_ipsec_tunnel_param {
  * IPsec Security Association option flags
  */
 struct rte_security_ipsec_sa_options {
-	/**< Extended Sequence Numbers (ESN)
+	/** Extended Sequence Numbers (ESN)
 	 *
 	 * * 1: Use extended (64 bit) sequence numbers
 	 * * 0: Use normal sequence numbers
 	 */
 	uint32_t esn : 1;
 
-	/**< UDP encapsulation
+	/** UDP encapsulation
 	 *
 	 * * 1: Do UDP encapsulation/decapsulation so that IPSEC packets can
 	 *      traverse through NAT boxes.
@@ -130,7 +130,7 @@ struct rte_security_ipsec_sa_options {
 	 */
 	uint32_t udp_encap : 1;
 
-	/**< Copy DSCP bits
+	/** Copy DSCP bits
 	 *
 	 * * 1: Copy IPv4 or IPv6 DSCP bits from inner IP header to
 	 *      the outer IP header in encapsulation, and vice versa in
@@ -139,7 +139,7 @@ struct rte_security_ipsec_sa_options {
 	 */
 	uint32_t copy_dscp : 1;
 
-	/**< Copy IPv6 Flow Label
+	/** Copy IPv6 Flow Label
 	 *
 	 * * 1: Copy IPv6 flow label from inner IPv6 header to the
 	 *      outer IPv6 header.
@@ -147,7 +147,7 @@ struct rte_security_ipsec_sa_options {
 	 */
 	uint32_t copy_flabel : 1;
 
-	/**< Copy IPv4 Don't Fragment bit
+	/** Copy IPv4 Don't Fragment bit
 	 *
 	 * * 1: Copy the DF bit from the inner IPv4 header to the outer
 	 *      IPv4 header.
@@ -155,7 +155,7 @@ struct rte_security_ipsec_sa_options {
 	 */
 	uint32_t copy_df : 1;
 
-	/**< Decrement inner packet Time To Live (TTL) field
+	/** Decrement inner packet Time To Live (TTL) field
 	 *
 	 * * 1: In tunnel mode, decrement inner packet IPv4 TTL or
 	 *      IPv6 Hop Limit after tunnel decapsulation, or before tunnel
@@ -164,7 +164,7 @@ struct rte_security_ipsec_sa_options {
 	 */
 	uint32_t dec_ttl : 1;
 
-	/**< Explicit Congestion Notification (ECN)
+	/** Explicit Congestion Notification (ECN)
 	 *
 	 * * 1: In tunnel mode, enable outer header ECN Field copied from
 	 *      inner header in tunnel encapsulation, or inner header ECN
-- 
2.7.4

Re: [dpdk-dev] [PATCH v2] security: update doxygen fields

[Akhil Goyal]

> 
> Replace /**< with /** for multiline doxygen comments.
> 
> Fixes: c261d1431bd8 ("security: introduce security API and framework")
> Cc: stable@dpdk.org
> 
> Signed-off-by: Radu Nicolau <radu.nicolau@intel.com>
> Acked-by: Akhil Goyal <akhil.goyal@nxp.com>
> Acked-by: Anoob Joseph <anoobj@marvell.com>
> ---
Applied to dpdk-next-crypto

Thanks.