diff mbox series

[net-next] net: ceph: Fix most of the kerneldoc warings

Message ID 20201028005907.930575-1-andrew@lunn.ch (mailing list archive)
State Not Applicable
Delegated to: Netdev Maintainers
Headers show
Series [net-next] net: ceph: Fix most of the kerneldoc warings | expand

Commit Message

Andrew Lunn Oct. 28, 2020, 12:59 a.m. UTC
net/ceph/cls_lock_client.c:143: warning: Function parameter or member 'oid' not described in 'ceph_cls_break_lock'
net/ceph/cls_lock_client.c:143: warning: Function parameter or member 'oloc' not described in 'ceph_cls_break_lock'
net/ceph/cls_lock_client.c:143: warning: Function parameter or member 'osdc' not described in 'ceph_cls_break_lock'
net/ceph/cls_lock_client.c:28: warning: Function parameter or member 'oid' not described in 'ceph_cls_lock'
net/ceph/cls_lock_client.c:28: warning: Function parameter or member 'oloc' not described in 'ceph_cls_lock'
net/ceph/cls_lock_client.c:28: warning: Function parameter or member 'osdc' not described in 'ceph_cls_lock'
net/ceph/cls_lock_client.c:93: warning: Function parameter or member 'oid' not described in 'ceph_cls_unlock'
net/ceph/cls_lock_client.c:93: warning: Function parameter or member 'oloc' not described in 'ceph_cls_unlock'
net/ceph/cls_lock_client.c:93: warning: Function parameter or member 'osdc' not described in 'ceph_cls_unlock'
net/ceph/crush/mapper.c:466: warning: Function parameter or member 'choose_args' not described in 'crush_choose_firstn'
net/ceph/crush/mapper.c:466: warning: Function parameter or member 'weight_max' not described in 'crush_choose_firstn'
net/ceph/crush/mapper.c:466: warning: Function parameter or member 'weight' not described in 'crush_choose_firstn'
net/ceph/crush/mapper.c:466: warning: Function parameter or member 'work' not described in 'crush_choose_firstn'
net/ceph/crush/mapper.c:655: warning: Function parameter or member 'bucket' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or member 'choose_args' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or member 'map' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or member 'numrep' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or member 'out2' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or member 'out' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or member 'outpos' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or member 'parent_r' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or member 'recurse_to_leaf' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or member 'recurse_tries' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or member 'tries' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or member 'type' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or member 'weight_max' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or member 'weight' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or member 'work' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or member 'x' not described in 'crush_choose_indep'

Signed-off-by: Andrew Lunn <andrew@lunn.ch>
---
 net/ceph/cls_lock_client.c | 12 +++++++++---
 net/ceph/crush/mapper.c    | 21 ++++++++++++++++++++-
 2 files changed, 29 insertions(+), 4 deletions(-)

Comments

Andrew Lunn Oct. 28, 2020, 1:06 a.m. UTC | #1
As the subject suggests, there is still one warning left:

net/ceph/crush/mapper.c:674: warning: Function parameter or member 'left' not described in 'crush_choose_indep'

It would be nice if somebody who understands this code could fix that
warning. Then ceph become W=1 clean.

	 Andrew
Jakub Kicinski Oct. 28, 2020, 1:09 a.m. UTC | #2
On Wed, 28 Oct 2020 01:59:07 +0100 Andrew Lunn wrote:
> net/ceph/cls_lock_client.c:143: warning: Function parameter or member 'oid' not described in 'ceph_cls_break_lock'
> net/ceph/cls_lock_client.c:143: warning: Function parameter or member 'oloc' not described in 'ceph_cls_break_lock'
> ...

I think this will be for Ilya and Jeff to pick up. Doesn't seem
particularly network-centric.
Andrew Lunn Oct. 28, 2020, 1:19 a.m. UTC | #3
On Tue, Oct 27, 2020 at 06:09:08PM -0700, Jakub Kicinski wrote:
> On Wed, 28 Oct 2020 01:59:07 +0100 Andrew Lunn wrote:
> > net/ceph/cls_lock_client.c:143: warning: Function parameter or member 'oid' not described in 'ceph_cls_break_lock'
> > net/ceph/cls_lock_client.c:143: warning: Function parameter or member 'oloc' not described in 'ceph_cls_break_lock'
> > ...
> 
> I think this will be for Ilya and Jeff to pick up. Doesn't seem
> particularly network-centric.

Hi Jakub

I want with what get_maintainers said:

$ ./scripts/get_maintainer.pl 0001-net-ceph-Fix-most-of-the-kerneldoc-warings.patch 
Ilya Dryomov <idryomov@gmail.com> (supporter:CEPH COMMON CODE (LIBCEPH),commit_signer:2/3=67%)
Jeff Layton <jlayton@kernel.org> (supporter:CEPH COMMON CODE (LIBCEPH))
"David S. Miller" <davem@davemloft.net> (maintainer:NETWORKING [GENERAL])
Jakub Kicinski <kuba@kernel.org> (maintainer:NETWORKING [GENERAL])
"Gustavo A. R. Silva" <gustavoars@kernel.org> (commit_signer:1/3=33%,authored:1/3=33%,removed_lines:1/3=33%)
Andrew Lunn <andrew@lunn.ch> (commit_signer:1/3=33%,authored:1/3=33%,added_lines:20/22=91%,removed_lines:1/3=33%)
"Alexander A. Klimov" <grandmaster@al2klimov.de> (commit_signer:1/3=33%,authored:1/3=33%,removed_lines:1/3=33%)
ceph-devel@vger.kernel.org (open list:CEPH COMMON CODE (LIBCEPH))
netdev@vger.kernel.org (open list:NETWORKING [GENERAL])
linux-kernel@vger.kernel.org (open list)

But i did miss ceph-devel@vger.kernel.org :-(

    Andrew
Jeff Layton Nov. 2, 2020, 7:55 p.m. UTC | #4
On Wed, Oct 28, 2020 at 01:59:07AM +0100, Andrew Lunn wrote:
> net/ceph/cls_lock_client.c:143: warning: Function parameter or member 'oid' not described in 'ceph_cls_break_lock'
> net/ceph/cls_lock_client.c:143: warning: Function parameter or member 'oloc' not described in 'ceph_cls_break_lock'
> net/ceph/cls_lock_client.c:143: warning: Function parameter or member 'osdc' not described in 'ceph_cls_break_lock'
> net/ceph/cls_lock_client.c:28: warning: Function parameter or member 'oid' not described in 'ceph_cls_lock'
> net/ceph/cls_lock_client.c:28: warning: Function parameter or member 'oloc' not described in 'ceph_cls_lock'
> net/ceph/cls_lock_client.c:28: warning: Function parameter or member 'osdc' not described in 'ceph_cls_lock'
> net/ceph/cls_lock_client.c:93: warning: Function parameter or member 'oid' not described in 'ceph_cls_unlock'
> net/ceph/cls_lock_client.c:93: warning: Function parameter or member 'oloc' not described in 'ceph_cls_unlock'
> net/ceph/cls_lock_client.c:93: warning: Function parameter or member 'osdc' not described in 'ceph_cls_unlock'
> net/ceph/crush/mapper.c:466: warning: Function parameter or member 'choose_args' not described in 'crush_choose_firstn'
> net/ceph/crush/mapper.c:466: warning: Function parameter or member 'weight_max' not described in 'crush_choose_firstn'
> net/ceph/crush/mapper.c:466: warning: Function parameter or member 'weight' not described in 'crush_choose_firstn'
> net/ceph/crush/mapper.c:466: warning: Function parameter or member 'work' not described in 'crush_choose_firstn'
> net/ceph/crush/mapper.c:655: warning: Function parameter or member 'bucket' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or member 'choose_args' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or member 'map' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or member 'numrep' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or member 'out2' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or member 'out' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or member 'outpos' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or member 'parent_r' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or member 'recurse_to_leaf' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or member 'recurse_tries' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or member 'tries' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or member 'type' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or member 'weight_max' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or member 'weight' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or member 'work' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or member 'x' not described in 'crush_choose_indep'
> 
> Signed-off-by: Andrew Lunn <andrew@lunn.ch>
> ---
>  net/ceph/cls_lock_client.c | 12 +++++++++---
>  net/ceph/crush/mapper.c    | 21 ++++++++++++++++++++-
>  2 files changed, 29 insertions(+), 4 deletions(-)
> 

If you resend, please do cc ceph-devel.

> diff --git a/net/ceph/cls_lock_client.c b/net/ceph/cls_lock_client.c
> index 17447c19d937..b130f7b25ea0 100644
> --- a/net/ceph/cls_lock_client.c
> +++ b/net/ceph/cls_lock_client.c
> @@ -10,7 +10,9 @@
>  
>  /**
>   * ceph_cls_lock - grab rados lock for object
> - * @oid, @oloc: object to lock
> + * @osdc: osd client grabbing the lock
> + * @oid: object to lock

id of object to lock

> + * @oloc: object to lock

location of object to lock

>   * @lock_name: the name of the lock
>   * @type: lock type (CEPH_CLS_LOCK_EXCLUSIVE or CEPH_CLS_LOCK_SHARED)
>   * @cookie: user-defined identifier for this instance of the lock
> @@ -82,7 +84,9 @@ EXPORT_SYMBOL(ceph_cls_lock);
>  
>  /**
>   * ceph_cls_unlock - release rados lock for object
> - * @oid, @oloc: object to lock
> + * @osdc: osd client releasing the lock
> + * @oid: object to lock
> + * @oloc: object to lock

ditto

>   * @lock_name: the name of the lock
>   * @cookie: user-defined identifier for this instance of the lock
>   */
> @@ -130,7 +134,9 @@ EXPORT_SYMBOL(ceph_cls_unlock);
>  
>  /**
>   * ceph_cls_break_lock - release rados lock for object for specified client
> - * @oid, @oloc: object to lock
> + * @osdc: osd client braaking the lock
> + * @oid: object to lock
> + * @oloc: object to lock

ditto

>   * @lock_name: the name of the lock
>   * @cookie: user-defined identifier for this instance of the lock
>   * @locker: current lock owner
> diff --git a/net/ceph/crush/mapper.c b/net/ceph/crush/mapper.c
> index 7057f8db4f99..1b1c09006792 100644
> --- a/net/ceph/crush/mapper.c
> +++ b/net/ceph/crush/mapper.c
> @@ -429,7 +429,10 @@ static int is_out(const struct crush_map *map,
>  /**
>   * crush_choose_firstn - choose numrep distinct items of given type
>   * @map: the crush_map
> + * @work: working area for a CRUSH placement computation
>   * @bucket: the bucket we are choose an item from
> + * @weight: weight vector (for map leaves)
> + * @weight_max: size of weight vector
>   * @x: crush input value
>   * @numrep: the number of items to choose
>   * @type: the type of item to choose
> @@ -445,6 +448,7 @@ static int is_out(const struct crush_map *map,
>   * @vary_r: pass r to recursive calls
>   * @out2: second output vector for leaf items (if @recurse_to_leaf)
>   * @parent_r: r value passed from the parent
> + * @choose_args: weights and ids for each known bucket
>   */
>  static int crush_choose_firstn(const struct crush_map *map,
>  			       struct crush_work *work,
> @@ -638,7 +642,22 @@ static int crush_choose_firstn(const struct crush_map *map,
>  
>  /**
>   * crush_choose_indep: alternative breadth-first positionally stable mapping
> - *
> + * @map: the crush_map
> + * @work: working area for a CRUSH placement computation
> + * @bucket: the bucket we are choose an item from
> + * @weight: weight vector (for map leaves)
> + * @weight_max: size of weight vector
> + * @x: crush input value
> + * @numrep: the number of items to choose
> + * @type: the type of item to choose
> + * @out: pointer to output vector
> + * @outpos: our position in that vector
> + * @tries: number of attempts to make
> + * @recurse_tries: number of attempts to have recursive chooseleaf make
> + * @recurse_to_leaf: true if we want one device under each item of given type (chooseleaf instead of choose)
> + * @out2: second output vector for leaf items (if @recurse_to_leaf)
> + * @parent_r: r value passed from the parent
> + * @choose_args: weights and ids for each known bucket
>   */
>  static void crush_choose_indep(const struct crush_map *map,
>  			       struct crush_work *work,
> -- 
> 2.28.0
>
Andrew Lunn Nov. 2, 2020, 8:11 p.m. UTC | #5
On Mon, Nov 02, 2020 at 02:55:03PM -0500, Jeffrey Layton wrote:
> On Wed, Oct 28, 2020 at 01:59:07AM +0100, Andrew Lunn wrote:
> > net/ceph/cls_lock_client.c:143: warning: Function parameter or member 'oid' not described in 'ceph_cls_break_lock'
> > net/ceph/cls_lock_client.c:143: warning: Function parameter or member 'oloc' not described in 'ceph_cls_break_lock'
> > net/ceph/cls_lock_client.c:143: warning: Function parameter or member 'osdc' not described in 'ceph_cls_break_lock'
> > net/ceph/cls_lock_client.c:28: warning: Function parameter or member 'oid' not described in 'ceph_cls_lock'
> > net/ceph/cls_lock_client.c:28: warning: Function parameter or member 'oloc' not described in 'ceph_cls_lock'
> > net/ceph/cls_lock_client.c:28: warning: Function parameter or member 'osdc' not described in 'ceph_cls_lock'
> > net/ceph/cls_lock_client.c:93: warning: Function parameter or member 'oid' not described in 'ceph_cls_unlock'
> > net/ceph/cls_lock_client.c:93: warning: Function parameter or member 'oloc' not described in 'ceph_cls_unlock'
> > net/ceph/cls_lock_client.c:93: warning: Function parameter or member 'osdc' not described in 'ceph_cls_unlock'
> > net/ceph/crush/mapper.c:466: warning: Function parameter or member 'choose_args' not described in 'crush_choose_firstn'
> > net/ceph/crush/mapper.c:466: warning: Function parameter or member 'weight_max' not described in 'crush_choose_firstn'
> > net/ceph/crush/mapper.c:466: warning: Function parameter or member 'weight' not described in 'crush_choose_firstn'
> > net/ceph/crush/mapper.c:466: warning: Function parameter or member 'work' not described in 'crush_choose_firstn'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or member 'bucket' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or member 'choose_args' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or member 'map' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or member 'numrep' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or member 'out2' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or member 'out' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or member 'outpos' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or member 'parent_r' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or member 'recurse_to_leaf' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or member 'recurse_tries' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or member 'tries' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or member 'type' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or member 'weight_max' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or member 'weight' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or member 'work' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or member 'x' not described in 'crush_choose_indep'
> > 
> > Signed-off-by: Andrew Lunn <andrew@lunn.ch>
> > ---
> >  net/ceph/cls_lock_client.c | 12 +++++++++---
> >  net/ceph/crush/mapper.c    | 21 ++++++++++++++++++++-
> >  2 files changed, 29 insertions(+), 4 deletions(-)
> > 
> 
> If you resend, please do cc ceph-devel.

Hi Jeffrey

Thanks for the comments. I will rework my patch and resend.

       Andrew
diff mbox series

Patch

diff --git a/net/ceph/cls_lock_client.c b/net/ceph/cls_lock_client.c
index 17447c19d937..b130f7b25ea0 100644
--- a/net/ceph/cls_lock_client.c
+++ b/net/ceph/cls_lock_client.c
@@ -10,7 +10,9 @@ 
 
 /**
  * ceph_cls_lock - grab rados lock for object
- * @oid, @oloc: object to lock
+ * @osdc: osd client grabbing the lock
+ * @oid: object to lock
+ * @oloc: object to lock
  * @lock_name: the name of the lock
  * @type: lock type (CEPH_CLS_LOCK_EXCLUSIVE or CEPH_CLS_LOCK_SHARED)
  * @cookie: user-defined identifier for this instance of the lock
@@ -82,7 +84,9 @@  EXPORT_SYMBOL(ceph_cls_lock);
 
 /**
  * ceph_cls_unlock - release rados lock for object
- * @oid, @oloc: object to lock
+ * @osdc: osd client releasing the lock
+ * @oid: object to lock
+ * @oloc: object to lock
  * @lock_name: the name of the lock
  * @cookie: user-defined identifier for this instance of the lock
  */
@@ -130,7 +134,9 @@  EXPORT_SYMBOL(ceph_cls_unlock);
 
 /**
  * ceph_cls_break_lock - release rados lock for object for specified client
- * @oid, @oloc: object to lock
+ * @osdc: osd client braaking the lock
+ * @oid: object to lock
+ * @oloc: object to lock
  * @lock_name: the name of the lock
  * @cookie: user-defined identifier for this instance of the lock
  * @locker: current lock owner
diff --git a/net/ceph/crush/mapper.c b/net/ceph/crush/mapper.c
index 7057f8db4f99..1b1c09006792 100644
--- a/net/ceph/crush/mapper.c
+++ b/net/ceph/crush/mapper.c
@@ -429,7 +429,10 @@  static int is_out(const struct crush_map *map,
 /**
  * crush_choose_firstn - choose numrep distinct items of given type
  * @map: the crush_map
+ * @work: working area for a CRUSH placement computation
  * @bucket: the bucket we are choose an item from
+ * @weight: weight vector (for map leaves)
+ * @weight_max: size of weight vector
  * @x: crush input value
  * @numrep: the number of items to choose
  * @type: the type of item to choose
@@ -445,6 +448,7 @@  static int is_out(const struct crush_map *map,
  * @vary_r: pass r to recursive calls
  * @out2: second output vector for leaf items (if @recurse_to_leaf)
  * @parent_r: r value passed from the parent
+ * @choose_args: weights and ids for each known bucket
  */
 static int crush_choose_firstn(const struct crush_map *map,
 			       struct crush_work *work,
@@ -638,7 +642,22 @@  static int crush_choose_firstn(const struct crush_map *map,
 
 /**
  * crush_choose_indep: alternative breadth-first positionally stable mapping
- *
+ * @map: the crush_map
+ * @work: working area for a CRUSH placement computation
+ * @bucket: the bucket we are choose an item from
+ * @weight: weight vector (for map leaves)
+ * @weight_max: size of weight vector
+ * @x: crush input value
+ * @numrep: the number of items to choose
+ * @type: the type of item to choose
+ * @out: pointer to output vector
+ * @outpos: our position in that vector
+ * @tries: number of attempts to make
+ * @recurse_tries: number of attempts to have recursive chooseleaf make
+ * @recurse_to_leaf: true if we want one device under each item of given type (chooseleaf instead of choose)
+ * @out2: second output vector for leaf items (if @recurse_to_leaf)
+ * @parent_r: r value passed from the parent
+ * @choose_args: weights and ids for each known bucket
  */
 static void crush_choose_indep(const struct crush_map *map,
 			       struct crush_work *work,