[PATCH net-next 0/2] libceph: fix kernel-doc warnings

[PATCH net-next 0/2] libceph: fix kernel-doc warnings

[Jeff Johnson]

I split this into two patches due to the nature of the two fixes.
Let me know if you prefer them to be squashed.

---
Jeff Johnson (2):
      libceph: suppress crush_choose_indep() kernel-doc warnings
      libceph: fix crush_choose_firstn() kernel-doc warnings

 net/ceph/crush/mapper.c | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)
---
base-commit: 523b23f0bee3014a7a752c9bb9f5c54f0eddae88
change-id: 20240710-kd-crush_choose_indep-02a9f906efe4

[PATCH net-next 1/2] libceph: suppress crush_choose_indep() kernel-doc warnings

[Jeff Johnson]

Currently, when built with "make W=1", the following warnings are
generated:
net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'map' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'work' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'bucket' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'weight' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'weight_max' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'x' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'left' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'numrep' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'type' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'out' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'outpos' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'tries' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'recurse_tries' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'recurse_to_leaf' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'out2' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'parent_r' not described in 'crush_choose_indep'
net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'choose_args' not described in 'crush_choose_indep'

These warnings are generated because the prologue comment for
crush_choose_indep() uses the kernel-doc prefix, but the actual
comment is a very brief description that is not in kernel-doc
format. Since this is a static function there is no need to fully
document the function, so replace the kernel-doc comment prefix with a
standard comment prefix to remove these warnings.

Signed-off-by: Jeff Johnson <quic_jjohnson@quicinc.com>
---
 net/ceph/crush/mapper.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/net/ceph/crush/mapper.c b/net/ceph/crush/mapper.c
index 1daf95e17d67..3194d5090963 100644
--- a/net/ceph/crush/mapper.c
+++ b/net/ceph/crush/mapper.c
@@ -636,7 +636,7 @@ static int crush_choose_firstn(const struct crush_map *map,
 }
 
 
-/**
+/*
  * crush_choose_indep: alternative breadth-first positionally stable mapping
  *
  */

-- 
2.42.0

[PATCH net-next 2/2] libceph: fix crush_choose_firstn() kernel-doc warnings

[Jeff Johnson]

Currently, when built with "make W=1", the following warnings are
generated:

net/ceph/crush/mapper.c:466: warning: Function parameter or struct member 'work' not described in 'crush_choose_firstn'
net/ceph/crush/mapper.c:466: warning: Function parameter or struct member 'weight' not described in 'crush_choose_firstn'
net/ceph/crush/mapper.c:466: warning: Function parameter or struct member 'weight_max' not described in 'crush_choose_firstn'
net/ceph/crush/mapper.c:466: warning: Function parameter or struct member 'choose_args' not described in 'crush_choose_firstn'

Update the crush_choose_firstn() kernel-doc to document these
parameters.

Signed-off-by: Jeff Johnson <quic_jjohnson@quicinc.com>
---
 net/ceph/crush/mapper.c | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/net/ceph/crush/mapper.c b/net/ceph/crush/mapper.c
index 3194d5090963..16a0f7e63d37 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: crush workspace initialized by crush_init_workspace()
  * @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,

-- 
2.42.0

Re: [PATCH net-next 1/2] libceph: suppress crush_choose_indep() kernel-doc warnings

[Simon Horman]

On Wed, Jul 10, 2024 at 11:10:03AM -0700, Jeff Johnson wrote:
> Currently, when built with "make W=1", the following warnings are
> generated:
> net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'map' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'work' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'bucket' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'weight' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'weight_max' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'x' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'left' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'numrep' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'type' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'out' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'outpos' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'tries' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'recurse_tries' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'recurse_to_leaf' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'out2' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'parent_r' not described in 'crush_choose_indep'
> net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'choose_args' not described in 'crush_choose_indep'
> 
> These warnings are generated because the prologue comment for
> crush_choose_indep() uses the kernel-doc prefix, but the actual
> comment is a very brief description that is not in kernel-doc
> format. Since this is a static function there is no need to fully
> document the function, so replace the kernel-doc comment prefix with a
> standard comment prefix to remove these warnings.
> 
> Signed-off-by: Jeff Johnson <quic_jjohnson@quicinc.com>

Reviewed-by: Simon Horman <horms@kernel.org>

Re: [PATCH net-next 2/2] libceph: fix crush_choose_firstn() kernel-doc warnings

[Simon Horman]

On Wed, Jul 10, 2024 at 11:10:04AM -0700, Jeff Johnson wrote:
> Currently, when built with "make W=1", the following warnings are
> generated:
> 
> net/ceph/crush/mapper.c:466: warning: Function parameter or struct member 'work' not described in 'crush_choose_firstn'
> net/ceph/crush/mapper.c:466: warning: Function parameter or struct member 'weight' not described in 'crush_choose_firstn'
> net/ceph/crush/mapper.c:466: warning: Function parameter or struct member 'weight_max' not described in 'crush_choose_firstn'
> net/ceph/crush/mapper.c:466: warning: Function parameter or struct member 'choose_args' not described in 'crush_choose_firstn'
> 
> Update the crush_choose_firstn() kernel-doc to document these
> parameters.
> 
> Signed-off-by: Jeff Johnson <quic_jjohnson@quicinc.com>

Reviewed-by: Simon Horman <horms@kernel.org>

Re: [PATCH net-next 1/2] libceph: suppress crush_choose_indep() kernel-doc warnings

[Ilya Dryomov]

On Thu, Jul 11, 2024 at 3:34 PM Simon Horman <horms@kernel.org> wrote:
>
> On Wed, Jul 10, 2024 at 11:10:03AM -0700, Jeff Johnson wrote:
> > Currently, when built with "make W=1", the following warnings are
> > generated:
> > net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'map' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'work' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'bucket' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'weight' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'weight_max' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'x' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'left' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'numrep' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'type' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'out' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'outpos' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'tries' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'recurse_tries' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'recurse_to_leaf' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'out2' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'parent_r' not described in 'crush_choose_indep'
> > net/ceph/crush/mapper.c:655: warning: Function parameter or struct member 'choose_args' not described in 'crush_choose_indep'
> >
> > These warnings are generated because the prologue comment for
> > crush_choose_indep() uses the kernel-doc prefix, but the actual
> > comment is a very brief description that is not in kernel-doc
> > format. Since this is a static function there is no need to fully
> > document the function, so replace the kernel-doc comment prefix with a
> > standard comment prefix to remove these warnings.
> >
> > Signed-off-by: Jeff Johnson <quic_jjohnson@quicinc.com>
>
> Reviewed-by: Simon Horman <horms@kernel.org>

Applied with a small tweak.

Thanks,

                Ilya

Re: [PATCH net-next 2/2] libceph: fix crush_choose_firstn() kernel-doc warnings

[Ilya Dryomov]

On Thu, Jul 11, 2024 at 3:34 PM Simon Horman <horms@kernel.org> wrote:
>
> On Wed, Jul 10, 2024 at 11:10:04AM -0700, Jeff Johnson wrote:
> > Currently, when built with "make W=1", the following warnings are
> > generated:
> >
> > net/ceph/crush/mapper.c:466: warning: Function parameter or struct member 'work' not described in 'crush_choose_firstn'
> > net/ceph/crush/mapper.c:466: warning: Function parameter or struct member 'weight' not described in 'crush_choose_firstn'
> > net/ceph/crush/mapper.c:466: warning: Function parameter or struct member 'weight_max' not described in 'crush_choose_firstn'
> > net/ceph/crush/mapper.c:466: warning: Function parameter or struct member 'choose_args' not described in 'crush_choose_firstn'
> >
> > Update the crush_choose_firstn() kernel-doc to document these
> > parameters.
> >
> > Signed-off-by: Jeff Johnson <quic_jjohnson@quicinc.com>
>
> Reviewed-by: Simon Horman <horms@kernel.org>

Applied with a small tweak.

Thanks,

                Ilya