diff mbox series

[v2,01/83] lib: update documentation of XXX_free() functions

Message ID 20220124174719.14417-2-stephen@networkplumber.org (mailing list archive)
State Superseded, archived
Delegated to: Thomas Monjalon
Headers show
Series remove unnecessary null checks | expand

Checks

Context Check Description
ci/checkpatch success coding style OK

Commit Message

Stephen Hemminger Jan. 24, 2022, 5:45 p.m. UTC
These functions all behave like libc free() and do
nothing if handed a NULL pointer. The code is already doing
this, this patch just documents the behavior.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 lib/hash/rte_hash.h       | 3 +++
 lib/kvargs/rte_kvargs.h   | 2 ++
 lib/mbuf/rte_mbuf.h       | 2 ++
 lib/mempool/rte_mempool.h | 2 ++
 lib/ring/rte_ring.h       | 2 ++
 5 files changed, 11 insertions(+)

Comments

Thomas Monjalon Jan. 28, 2022, 9:47 p.m. UTC | #1
24/01/2022 18:45, Stephen Hemminger:
> These functions all behave like libc free() and do
> nothing if handed a NULL pointer. The code is already doing
> this, this patch just documents the behavior.
> 
> Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
> ---
>  /**
>   * De-allocate all memory used by hash table.
> + *
> + * If the pointer is NULL, the function does nothing.

Would be better to move in the context of the parameter.

> + *
>   * @param h
>   *   Hash table to free

Here:
	If NULL, the function does nothing.

Same for comment for all files of this patch.

> @@ -108,6 +108,8 @@ struct rte_kvargs *rte_kvargs_parse_delim(const char *args,
>   * Free a rte_kvargs structure previously allocated with
>   * rte_kvargs_parse().
>   *
> + * If the pointer is NULL, the function does nothing.
> + *
>   * @param kvlist
>   *   The rte_kvargs structure. No error if NULL.

Would need to reword "No error" to "Does nothing".

> @@ -1372,6 +1372,8 @@ rte_pktmbuf_free_seg(struct rte_mbuf *m)
>   * Free an mbuf, and all its segments in case of chained buffers. Each
>   * segment is added back into its original mempool.
>   *
> + * If the pointer is NULL, the function does nothing.
> + *
>   * @param m
>   *   The packet mbuf to be freed. If NULL, the function does nothing.

Here the comment exists already in the right place.
Stephen Hemminger Jan. 28, 2022, 10:51 p.m. UTC | #2
On Fri, 28 Jan 2022 22:47:15 +0100
Thomas Monjalon <thomas@monjalon.net> wrote:

> 24/01/2022 18:45, Stephen Hemminger:
> > These functions all behave like libc free() and do
> > nothing if handed a NULL pointer. The code is already doing
> > this, this patch just documents the behavior.
> > 
> > Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
> > ---
> >  /**
> >   * De-allocate all memory used by hash table.
> > + *
> > + * If the pointer is NULL, the function does nothing.  
> 
> Would be better to move in the context of the parameter

I copied text from rte_free to other functions...
For consistency, lets document it one way in all cases.
Don't care which one...
Thomas Monjalon Jan. 29, 2022, 6:51 p.m. UTC | #3
28/01/2022 23:51, Stephen Hemminger:
> On Fri, 28 Jan 2022 22:47:15 +0100
> Thomas Monjalon <thomas@monjalon.net> wrote:
> 
> > 24/01/2022 18:45, Stephen Hemminger:
> > > These functions all behave like libc free() and do
> > > nothing if handed a NULL pointer. The code is already doing
> > > this, this patch just documents the behavior.
> > > 
> > > Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
> > > ---
> > >  /**
> > >   * De-allocate all memory used by hash table.
> > > + *
> > > + * If the pointer is NULL, the function does nothing.  
> > 
> > Would be better to move in the context of the parameter
> 
> I copied text from rte_free to other functions...
> For consistency, lets document it one way in all cases.
> Don't care which one...

I prefer to have comments about a parameter inside the @param please.
Thomas Monjalon Feb. 8, 2022, 5:03 p.m. UTC | #4
29/01/2022 19:51, Thomas Monjalon:
> 28/01/2022 23:51, Stephen Hemminger:
> > On Fri, 28 Jan 2022 22:47:15 +0100
> > Thomas Monjalon <thomas@monjalon.net> wrote:
> > 
> > > 24/01/2022 18:45, Stephen Hemminger:
> > > > These functions all behave like libc free() and do
> > > > nothing if handed a NULL pointer. The code is already doing
> > > > this, this patch just documents the behavior.
> > > > 
> > > > Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
> > > > ---
> > > >  /**
> > > >   * De-allocate all memory used by hash table.
> > > > + *
> > > > + * If the pointer is NULL, the function does nothing.  
> > > 
> > > Would be better to move in the context of the parameter
> > 
> > I copied text from rte_free to other functions...
> > For consistency, lets document it one way in all cases.
> > Don't care which one...
> 
> I prefer to have comments about a parameter inside the @param please.

Please would you provide a v3 before -rc1?
diff mbox series

Patch

diff --git a/lib/hash/rte_hash.h b/lib/hash/rte_hash.h
index 6067aad95431..94223cf81ae0 100644
--- a/lib/hash/rte_hash.h
+++ b/lib/hash/rte_hash.h
@@ -174,6 +174,9 @@  rte_hash_find_existing(const char *name);
 
 /**
  * De-allocate all memory used by hash table.
+ *
+ * If the pointer is NULL, the function does nothing.
+ *
  * @param h
  *   Hash table to free
  */
diff --git a/lib/kvargs/rte_kvargs.h b/lib/kvargs/rte_kvargs.h
index 359a9f5b091c..bf1732ce2b1e 100644
--- a/lib/kvargs/rte_kvargs.h
+++ b/lib/kvargs/rte_kvargs.h
@@ -108,6 +108,8 @@  struct rte_kvargs *rte_kvargs_parse_delim(const char *args,
  * Free a rte_kvargs structure previously allocated with
  * rte_kvargs_parse().
  *
+ * If the pointer is NULL, the function does nothing.
+ *
  * @param kvlist
  *   The rte_kvargs structure. No error if NULL.
  */
diff --git a/lib/mbuf/rte_mbuf.h b/lib/mbuf/rte_mbuf.h
index dedf83c38d1b..cb280108d3f9 100644
--- a/lib/mbuf/rte_mbuf.h
+++ b/lib/mbuf/rte_mbuf.h
@@ -1372,6 +1372,8 @@  rte_pktmbuf_free_seg(struct rte_mbuf *m)
  * Free an mbuf, and all its segments in case of chained buffers. Each
  * segment is added back into its original mempool.
  *
+ * If the pointer is NULL, the function does nothing.
+ *
  * @param m
  *   The packet mbuf to be freed. If NULL, the function does nothing.
  */
diff --git a/lib/mempool/rte_mempool.h b/lib/mempool/rte_mempool.h
index 1e7a3c15273c..c268328b268b 100644
--- a/lib/mempool/rte_mempool.h
+++ b/lib/mempool/rte_mempool.h
@@ -1099,6 +1099,8 @@  rte_mempool_create_empty(const char *name, unsigned n, unsigned elt_size,
  * memory referenced by the mempool. The objects must not be used by
  * other cores as they will be freed.
  *
+ * If the pointer is NULL, the function does nothing.
+ *
  * @param mp
  *   A pointer to the mempool structure.
  */
diff --git a/lib/ring/rte_ring.h b/lib/ring/rte_ring.h
index da17ed6d7c04..c2faf7b3e6dc 100644
--- a/lib/ring/rte_ring.h
+++ b/lib/ring/rte_ring.h
@@ -176,6 +176,8 @@  struct rte_ring *rte_ring_create(const char *name, unsigned int count,
 /**
  * De-allocate all memory used by the ring.
  *
+ * If the pointer is NULL, the function does nothing.
+ *
  * @param r
  *   Ring to free
  */