[dpdk-dev] [PATCH] lib: fix doxygen syntax issues

[dpdk-dev] [PATCH] lib: fix doxygen syntax issues

[jerinj]

From: Jerin Jacob <jerinj@marvell.com>

Fix following syntax error reported by doxygen 1.9.5 version.

lib/eal/include/rte_uuid.h:89: error: RTE_UUID_STRLEN
has @param documentation sections but no arguments
(warning treated as error, aborting now)

lib/power/rte_power.h:169: error: rte_power_freq_up has
@param documentation sections but no arguments
(warning treated as error, aborting now)

Fixes: 6bc67c497a51 ("eal: add uuid API")
Fixes: d7937e2e3d12 ("power: initial import")
Cc: stable@dpdk.org

Signed-off-by: Jerin Jacob <jerinj@marvell.com>
---
 lib/eal/include/rte_uuid.h |  4 ++-
 lib/power/rte_power.h      | 55 --------------------------------------
 2 files changed, 3 insertions(+), 56 deletions(-)

diff --git a/lib/eal/include/rte_uuid.h b/lib/eal/include/rte_uuid.h
index 8b42e070af..cfefd4308a 100644
--- a/lib/eal/include/rte_uuid.h
+++ b/lib/eal/include/rte_uuid.h
@@ -37,6 +37,9 @@ typedef unsigned char rte_uuid_t[16];
 	((e) >> 8) & 0xff, (e) & 0xff		\
 }
 
+/** UUID string length */
+#define RTE_UUID_STRLEN	(36 + 1)
+
 /**
  * Test if UUID is all zeros.
  *
@@ -95,7 +98,6 @@ int	rte_uuid_parse(const char *in, rte_uuid_t uu);
  * @param len
  *    Sizeof the available string buffer
  */
-#define RTE_UUID_STRLEN	(36 + 1)
 void	rte_uuid_unparse(const rte_uuid_t uu, char *out, size_t len);
 
 #ifdef __cplusplus
diff --git a/lib/power/rte_power.h b/lib/power/rte_power.h
index 47345e26df..7954299489 100644
--- a/lib/power/rte_power.h
+++ b/lib/power/rte_power.h
@@ -169,14 +169,6 @@ typedef int (*rte_power_freq_change_t)(unsigned int lcore_id);
  * Scale up the frequency of a specific lcore according to the available
  * frequencies.
  * Review each environments specific documentation for usage.
- *
- * @param lcore_id
- *  lcore id.
- *
- * @return
- *  - 1 on success with frequency changed.
- *  - 0 on success without frequency changed.
- *  - Negative on error.
  */
 extern rte_power_freq_change_t rte_power_freq_up;
 
@@ -184,30 +176,13 @@ extern rte_power_freq_change_t rte_power_freq_up;
  * Scale down the frequency of a specific lcore according to the available
  * frequencies.
  * Review each environments specific documentation for usage.
- *
- * @param lcore_id
- *  lcore id.
- *
- * @return
- *  - 1 on success with frequency changed.
- *  - 0 on success without frequency changed.
- *  - Negative on error.
  */
-
 extern rte_power_freq_change_t rte_power_freq_down;
 
 /**
  * Scale up the frequency of a specific lcore to the highest according to the
  * available frequencies.
  * Review each environments specific documentation for usage.
- *
- * @param lcore_id
- *  lcore id.
- *
- * @return
- *  - 1 on success with frequency changed.
- *  - 0 on success without frequency changed.
- *  - Negative on error.
  */
 extern rte_power_freq_change_t rte_power_freq_max;
 
@@ -215,54 +190,24 @@ extern rte_power_freq_change_t rte_power_freq_max;
  * Scale down the frequency of a specific lcore to the lowest according to the
  * available frequencies.
  * Review each environments specific documentation for usage..
- *
- * @param lcore_id
- *  lcore id.
- *
- * @return
- *  - 1 on success with frequency changed.
- *  - 0 on success without frequency changed.
- *  - Negative on error.
  */
 extern rte_power_freq_change_t rte_power_freq_min;
 
 /**
  * Query the Turbo Boost status of a specific lcore.
  * Review each environments specific documentation for usage..
- *
- * @param lcore_id
- *  lcore id.
- *
- * @return
- *  - 1 Turbo Boost is enabled for this lcore.
- *  - 0 Turbo Boost is disabled for this lcore.
- *  - Negative on error.
  */
 extern rte_power_freq_change_t rte_power_turbo_status;
 
 /**
  * Enable Turbo Boost for this lcore.
  * Review each environments specific documentation for usage..
- *
- * @param lcore_id
- *  lcore id.
- *
- * @return
- *  - 0 on success.
- *  - Negative on error.
  */
 extern rte_power_freq_change_t rte_power_freq_enable_turbo;
 
 /**
  * Disable Turbo Boost for this lcore.
  * Review each environments specific documentation for usage..
- *
- * @param lcore_id
- *  lcore id.
- *
- * @return
- *  - 0 on success.
- *  - Negative on error.
  */
 extern rte_power_freq_change_t rte_power_freq_disable_turbo;
 
-- 
2.38.1

Re: [dpdk-dev] [PATCH] lib: fix doxygen syntax issues

[Thomas Monjalon]

09/11/2022 15:54, jerinj@marvell.com:
> From: Jerin Jacob <jerinj@marvell.com>
> 
> Fix following syntax error reported by doxygen 1.9.5 version.
> 
> lib/eal/include/rte_uuid.h:89: error: RTE_UUID_STRLEN
> has @param documentation sections but no arguments
> (warning treated as error, aborting now)
> 
> lib/power/rte_power.h:169: error: rte_power_freq_up has
> @param documentation sections but no arguments
> (warning treated as error, aborting now)
> 
> Fixes: 6bc67c497a51 ("eal: add uuid API")
> Fixes: d7937e2e3d12 ("power: initial import")

I think it deserves to be split in 2 patches.
If you agree, I can split when merging.

Re: [dpdk-dev] [PATCH] lib: fix doxygen syntax issues

[Jerin Jacob]

On Wed, Nov 9, 2022 at 8:34 PM Thomas Monjalon <thomas@monjalon.net> wrote:
>
> 09/11/2022 15:54, jerinj@marvell.com:
> > From: Jerin Jacob <jerinj@marvell.com>
> >
> > Fix following syntax error reported by doxygen 1.9.5 version.
> >
> > lib/eal/include/rte_uuid.h:89: error: RTE_UUID_STRLEN
> > has @param documentation sections but no arguments
> > (warning treated as error, aborting now)
> >
> > lib/power/rte_power.h:169: error: rte_power_freq_up has
> > @param documentation sections but no arguments
> > (warning treated as error, aborting now)
> >
> > Fixes: 6bc67c497a51 ("eal: add uuid API")
> > Fixes: d7937e2e3d12 ("power: initial import")
>
> I think it deserves to be split in 2 patches.
> If you agree, I can split when merging.

OK

>
>
>

Re: [dpdk-dev] [PATCH] lib: fix doxygen syntax issues

[David Marchand]

On Wed, Nov 9, 2022 at 3:54 PM <jerinj@marvell.com> wrote:
>
> From: Jerin Jacob <jerinj@marvell.com>
>
> Fix following syntax error reported by doxygen 1.9.5 version.
>
> lib/eal/include/rte_uuid.h:89: error: RTE_UUID_STRLEN
> has @param documentation sections but no arguments
> (warning treated as error, aborting now)
>
> lib/power/rte_power.h:169: error: rte_power_freq_up has
> @param documentation sections but no arguments
> (warning treated as error, aborting now)
>
> Fixes: 6bc67c497a51 ("eal: add uuid API")
> Fixes: d7937e2e3d12 ("power: initial import")
> Cc: stable@dpdk.org
>
> Signed-off-by: Jerin Jacob <jerinj@marvell.com>

I split the patch in two (as Thomas suggested) and applied it.
Thanks.


-- 
David Marchand