Re: [PATCH v2 net-next] net/iucv: clean up iucv kernel-doc warnings

[Alexandra Winter <wintera@linux.ibm.com>]

On 01.02.26 08:23, Randy Dunlap wrote:
> Fix numerous (many) kernel-doc warnings in iucv.[ch]:
> 
> - remove kernel-doc on static functions in iucv.c
> - convert function documentation comments to a common (kernel-doc) look,
>   even for static functions (without "/**")
> - use matching parameter and parameter description names
> 
> Examples:
> 
> Warning: include/net/iucv/iucv.h:210 missing initial short description
>  on line: * iucv_unregister
> Warning: include/net/iucv/iucv.h:216 function parameter 'handle' not
>  described in 'iucv_unregister'
> Warning: include/net/iucv/iucv.h:467 function parameter 'answer' not
>  described in 'iucv_message_send2way'
> Warning: net/iucv/iucv.c:727 missing initial short description on line:
>  * iucv_cleanup_queue
> 
> Build-tested with both "make htmldocs" and "make ARCH=s390 defconfig all".
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> ---

Thank you very much for your effort Randy.
FYI: I had to use 'scripts/kernel-doc.py -none -Wall include/net/iucv/*' to see the warnings.



> v2:
> - correct verbs in descriptions of 2 functions (Jakub)
> - removed duplicate kernel-doc comments from the header file (Jakub)
> 
> Cc: Alexandra Winter <wintera@linux.ibm.com>
> Cc: Thorsten Winkler <twinkler@linux.ibm.com>
> Cc: linux-s390@vger.kernel.org
> Cc: "David S. Miller" <davem@davemloft.net>
> Cc: Eric Dumazet <edumazet@google.com>
> Cc: Jakub Kicinski <kuba@kernel.org>
> Cc: Paolo Abeni <pabeni@redhat.com>
> Cc: Simon Horman <horms@kernel.org>
> 
>  include/net/iucv/iucv.h |  209 ------------------------------
>  net/iucv/iucv.c         |  259 ++++++++++++++++++--------------------
>  2 files changed, 128 insertions(+), 340 deletions(-)
> 
> --- linux-next-20260130.orig/include/net/iucv/iucv.h
> +++ linux-next-20260130/include/net/iucv/iucv.h
> @@ -70,7 +70,7 @@
>  #define IUCV_IPLOCAL	0x01
>  
>  /*
> - * iucv_array : Defines buffer array.
> + * iucv_array - Defines buffer array.

Did that create a kernel doc warning? It's a struct, not a function.
I propose
+ * struct iucv_array
like other structs in this file.

[...]

> @@ -757,13 +742,12 @@ static void iucv_cleanup_queue(void)
>  }
>
>  /**
> - * iucv_register:
> + * iucv_register - Registers a driver with IUCV.
> + *
>   * @handler: address of iucv handler structure
>   * @smp: != 0 indicates that the handler can deal with out of order messages
>   *
> - * Registers a driver with IUCV.
> - *
> - * Returns 0 on success, -ENOMEM if the memory allocation for the pathid
> + * Returns: 0 on success, -ENOMEM if the memory allocation for the pathid
>   * table failed, or -EIO if IUCV_DECLARE_BUFFER failed on all cpus.
>   */
>  int iucv_register(struct iucv_handler *handler, int smp)

Before this one, you changed /** to /*
after this one you left /**
That's a bit inconsistent.





All the fixes look good to me. And they get rid of the mentioned warnings.
I appreciate your approach to use the existing wording, though it may not
be according to the latest style guidelines.

Reviewed-by: Alexandra Winter <wintera@linux.ibm.com>