linux-kernel - Re: [PATCH] block/rnbd: correct all kernel-doc complaints

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <CAMGffEkEU4obSxbtRUNaK8F03jQEaX2VDqHyWmsYSidDsf_94g@mail.gmail.com>
Date: Mon, 1 Dec 2025 07:10:15 +0100
From: Jinpu Wang <jinpu.wang@...os.com>
To: Randy Dunlap <rdunlap@...radead.org>
Cc: linux-kernel@...r.kernel.org, "Md. Haris Iqbal" <haris.iqbal@...os.com>, 
	Jens Axboe <axboe@...nel.dk>, linux-block@...r.kernel.org
Subject: Re: [PATCH] block/rnbd: correct all kernel-doc complaints

On Sat, Nov 29, 2025 at 11:35 PM Randy Dunlap <rdunlap@...radead.org> wrote:
>
> Fix all kernel-doc warnings in rnbd-proto.h:
> - use correct enum name in kdoc comment
> - mark several struct members as "/* private: */" so that no kdoc is
>   required for them
> - don't use "/**" for a non-kernel-doc comment
> - use the correct struct member name for "dev_name"
> - use " *" for a blank kernel-doc line
>
> Fixes these warnings:
> Warning: drivers/block/rnbd/rnbd-proto.h:41 expecting prototype for
>  enum rnbd_msg_types. Prototype was for enum rnbd_msg_type instead
> Warning: drivers/block/rnbd/rnbd-proto.h:50 struct member '__padding'
>  not described in 'rnbd_msg_hdr'
> Warning: drivers/block/rnbd/rnbd-proto.h:53 This comment starts with
>  '/**', but isn't a kernel-doc comment.
>  * We allow to map RO many times and RW only once. We allow to map yet another
> Warning: drivers/block/rnbd/rnbd-proto.h:81 struct member 'reserved'
>  not described in 'rnbd_msg_sess_info'
> Warning: drivers/block/rnbd/rnbd-proto.h:92 struct member 'reserved'
>  not described in 'rnbd_msg_sess_info_rsp'
> Warning: drivers/block/rnbd/rnbd-proto.h:107 struct member 'resv1'
>  not described in 'rnbd_msg_open'
> Warning: drivers/block/rnbd/rnbd-proto.h:107 struct member 'dev_name'
>  not described in 'rnbd_msg_open'
> Warning: drivers/block/rnbd/rnbd-proto.h:107 struct member 'reserved'
>  not described in 'rnbd_msg_open'
> Warning: drivers/block/rnbd/rnbd-proto.h:158 struct member 'reserved'
>  not described in 'rnbd_msg_open_rsp'
> Warning: drivers/block/rnbd/rnbd-proto.h:189 bad line:
>
> Signed-off-by: Randy Dunlap <rdunlap@...radead.org>
lgtm, thx!
Acked-by: Jack Wang <jinpu.wang@...os.com>
> ---
> Cc: Md. Haris Iqbal <haris.iqbal@...os.com>
> Cc: Jack Wang <jinpu.wang@...os.com>
> Cc: Jens Axboe <axboe@...nel.dk>
> Cc: linux-block@...r.kernel.org
> ---
>  drivers/block/rnbd/rnbd-proto.h |   15 +++++++++++----
>  1 file changed, 11 insertions(+), 4 deletions(-)
>
> --- linux-next-20251128.orig/drivers/block/rnbd/rnbd-proto.h
> +++ linux-next-20251128/drivers/block/rnbd/rnbd-proto.h
> @@ -24,7 +24,7 @@
>  #define RTRS_PORT 1234
>
>  /**
> - * enum rnbd_msg_types - RNBD message types
> + * enum rnbd_msg_type - RNBD message types
>   * @RNBD_MSG_SESS_INFO:        initial session info from client to server
>   * @RNBD_MSG_SESS_INFO_RSP:    initial session info from server to client
>   * @RNBD_MSG_OPEN:             open (map) device request
> @@ -47,10 +47,11 @@ enum rnbd_msg_type {
>   */
>  struct rnbd_msg_hdr {
>         __le16          type;
> +       /* private: */
>         __le16          __padding;
>  };
>
> -/**
> +/*
>   * We allow to map RO many times and RW only once. We allow to map yet another
>   * time RW, if MIGRATION is provided (second RW export can be required for
>   * example for VM migration)
> @@ -78,6 +79,7 @@ static const __maybe_unused struct {
>  struct rnbd_msg_sess_info {
>         struct rnbd_msg_hdr hdr;
>         u8              ver;
> +       /* private: */
>         u8              reserved[31];
>  };
>
> @@ -89,6 +91,7 @@ struct rnbd_msg_sess_info {
>  struct rnbd_msg_sess_info_rsp {
>         struct rnbd_msg_hdr hdr;
>         u8              ver;
> +       /* private: */
>         u8              reserved[31];
>  };
>
> @@ -97,13 +100,16 @@ struct rnbd_msg_sess_info_rsp {
>   * @hdr:               message header
>   * @access_mode:       the mode to open remote device, valid values see:
>   *                     enum rnbd_access_mode
> - * @device_name:       device path on remote side
> + * @dev_name:          device path on remote side
>   */
>  struct rnbd_msg_open {
>         struct rnbd_msg_hdr hdr;
>         u8              access_mode;
> +       /* private: */
>         u8              resv1;
> +       /* public: */
>         s8              dev_name[NAME_MAX];
> +       /* private: */
>         u8              reserved[3];
>  };
>
> @@ -155,6 +161,7 @@ struct rnbd_msg_open_rsp {
>         __le16                  secure_discard;
>         u8                      obsolete_rotational;
>         u8                      cache_policy;
> +       /* private: */
>         u8                      reserved[10];
>  };
>
> @@ -187,7 +194,7 @@ struct rnbd_msg_io {
>   * @RNBD_OP_DISCARD:        discard sectors
>   * @RNBD_OP_SECURE_ERASE:   securely erase sectors
>   * @RNBD_OP_WRITE_ZEROES:   write zeroes sectors
> -
> + *
>   * @RNBD_F_SYNC:            request is sync (sync write or read)
>   * @RNBD_F_FUA:             forced unit access
>   */