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

[Randy Dunlap <rdunlap@infradead.org>]

Hi,

On 2/2/26 7:35 AM, Alexandra Winter wrote:
> 
> 
> 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.

It's not kernel-doc, so no warning.
However, JFYI, for kernel-doc, it would need a "short description" after the
hyphen, whether it's a function, struct, enum, typedef, union, or define (macro).


> I propose
> + * struct iucv_array
> like other structs in this file.

OK, that's fine for structs that don't have kernel-doc notation.

> [...]
> 
>> @@ -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.

That's described in the patch description:

>> - remove kernel-doc on static functions in iucv.c

but I can restore the "/**" (i.e., not change them to "/*").
OK, I'll do that.


> 
> 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.

Is that IBM style guidelines or kernel?

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


I'll send a v3. Hopefully it will be satisfactory.

Thanks.
-- 
~Randy