* Re: [dpdk-dev] [EXT] [PATCH] security: update doxygen fields
2019-09-03 12:57 [dpdk-dev] [PATCH] security: update doxygen fields Radu Nicolau
@ 2019-09-04 3:41 ` Anoob Joseph
2019-09-04 7:46 ` Thomas Monjalon
2019-09-04 9:27 ` Akhil Goyal
2019-09-04 9:18 ` [dpdk-dev] " Akhil Goyal
` (2 subsequent siblings)
3 siblings, 2 replies; 8+ messages in thread
From: Anoob Joseph @ 2019-09-04 3:41 UTC (permalink / raw)
To: Radu Nicolau, dev, Thomas Monjalon, akhil.goyal
Cc: konstantin.ananyev, bernard.iremonger, declan.doherty, stephen
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
^ permalink raw reply [flat|nested] 8+ messages in thread* Re: [dpdk-dev] [EXT] [PATCH] security: update doxygen fields
2019-09-04 3:41 ` [dpdk-dev] [EXT] " Anoob Joseph
@ 2019-09-04 7:46 ` Thomas Monjalon
2019-09-04 9:27 ` Akhil Goyal
1 sibling, 0 replies; 8+ messages in thread
From: Thomas Monjalon @ 2019-09-04 7:46 UTC (permalink / raw)
To: Anoob Joseph
Cc: Radu Nicolau, dev, akhil.goyal, konstantin.ananyev,
bernard.iremonger, declan.doherty, stephen, ferruh.yigit
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.
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [dpdk-dev] [EXT] [PATCH] security: update doxygen fields
2019-09-04 3:41 ` [dpdk-dev] [EXT] " Anoob Joseph
2019-09-04 7:46 ` Thomas Monjalon
@ 2019-09-04 9:27 ` Akhil Goyal
1 sibling, 0 replies; 8+ messages in thread
From: Akhil Goyal @ 2019-09-04 9:27 UTC (permalink / raw)
To: Anoob Joseph, Radu Nicolau, dev, Thomas Monjalon
Cc: konstantin.ananyev, bernard.iremonger, declan.doherty, stephen
>
> 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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [dpdk-dev] [PATCH] security: update doxygen fields
2019-09-03 12:57 [dpdk-dev] [PATCH] security: update doxygen fields Radu Nicolau
2019-09-04 3:41 ` [dpdk-dev] [EXT] " Anoob Joseph
@ 2019-09-04 9:18 ` Akhil Goyal
2019-09-04 9:27 ` [dpdk-dev] [EXT] " Anoob Joseph
2019-09-04 11:03 ` [dpdk-dev] [PATCH v2] " Radu Nicolau
3 siblings, 0 replies; 8+ messages in thread
From: Akhil Goyal @ 2019-09-04 9:18 UTC (permalink / raw)
To: Radu Nicolau, dev
Cc: konstantin.ananyev, bernard.iremonger, declan.doherty, stephen, anoobj
>
> 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>
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [dpdk-dev] [EXT] [PATCH] security: update doxygen fields
2019-09-03 12:57 [dpdk-dev] [PATCH] security: update doxygen fields Radu Nicolau
2019-09-04 3:41 ` [dpdk-dev] [EXT] " Anoob Joseph
2019-09-04 9:18 ` [dpdk-dev] " Akhil Goyal
@ 2019-09-04 9:27 ` Anoob Joseph
2019-09-04 11:03 ` [dpdk-dev] [PATCH v2] " Radu Nicolau
3 siblings, 0 replies; 8+ messages in thread
From: Anoob Joseph @ 2019-09-04 9:27 UTC (permalink / raw)
To: Radu Nicolau, dev
Cc: akhil.goyal, konstantin.ananyev, bernard.iremonger,
declan.doherty, stephen
> -----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>
^ permalink raw reply [flat|nested] 8+ messages in thread
* [dpdk-dev] [PATCH v2] security: update doxygen fields
2019-09-03 12:57 [dpdk-dev] [PATCH] security: update doxygen fields Radu Nicolau
` (2 preceding siblings ...)
2019-09-04 9:27 ` [dpdk-dev] [EXT] " Anoob Joseph
@ 2019-09-04 11:03 ` Radu Nicolau
2019-09-19 15:10 ` Akhil Goyal
3 siblings, 1 reply; 8+ messages in thread
From: Radu Nicolau @ 2019-09-04 11:03 UTC (permalink / raw)
To: dev
Cc: akhil.goyal, konstantin.ananyev, bernard.iremonger,
declan.doherty, stephen, anoobj, thomas, Radu Nicolau, stable
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
^ permalink raw reply [flat|nested] 8+ messages in thread* Re: [dpdk-dev] [PATCH v2] security: update doxygen fields
2019-09-04 11:03 ` [dpdk-dev] [PATCH v2] " Radu Nicolau
@ 2019-09-19 15:10 ` Akhil Goyal
0 siblings, 0 replies; 8+ messages in thread
From: Akhil Goyal @ 2019-09-19 15:10 UTC (permalink / raw)
To: Radu Nicolau, dev
Cc: konstantin.ananyev, bernard.iremonger, declan.doherty, stephen,
anoobj, thomas, stable
>
> 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.
^ permalink raw reply [flat|nested] 8+ messages in thread