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

[Randy Dunlap <rdunlap@infradead.org>]

On 2/3/26 1:39 AM, Alexandra Winter wrote:
> 
> 
> On 03.02.26 08:52, Randy Dunlap wrote:
>> Fix numerous (many) kernel-doc warnings in iucv.[ch]:
>>
>> - convert function documentation comments to a common (kernel-doc) look,
>>   even for static functions (without "/**")
>> - use matching parameter and parameter description names
>> - use better wording in function descriptions (Jakub & AI)
>> - remove duplicate kernel-doc comments from the header file (Jakub)
>>
>> 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>
>> ---
>> v3:
>> - I didn't use Alexandra'a (v2) Reviewed-by: due to the number of changes.
>> - leave kernel-doc ("/**") on static functions in iucv.c (I did not
>>   convert other static functions to kernel-doc comments.)
> 
> Thank you. Feel free to add
> Reviewed-by: Alexandra Winter <wintera@linux.ibm.com>
> 
> 
> There are still warnings left about missing return value descriptions:
>> make W=2 clean net/iucv/ 2>&1 | grep ^Warning
> Warning: net/iucv/iucv.c:691 No description found for return value of 'iucv_sever_pathid'
> Warning: net/iucv/iucv.c:1099 No description found for return value of 'iucv_message_receive_iprmdata'
> Warning: net/iucv/iucv.c:1856 No description found for return value of 'iucv_init'
> Warning: net/iucv/iucv.c:691 No description found for return value of 'iucv_sever_pathid'
> Warning: net/iucv/iucv.c:1099 No description found for return value of 'iucv_message_receive_iprmdata'
> Warning: net/iucv/iucv.c:1856 No description found for return value of 'iucv_init'
> Warning: net/iucv/af_iucv.c:131 No description found for return value of 'iucv_msg_length'
> Warning: net/iucv/af_iucv.c:150 No description found for return value of 'iucv_sock_in_state'
> Warning: net/iucv/af_iucv.c:163 No description found for return value of 'iucv_below_msglim'
> Warning: net/iucv/af_iucv.c:889 No description found for return value of 'iucv_send_iprm'
> Warning: net/iucv/af_iucv.c:131 No description found for return value of 'iucv_msg_length'
> Warning: net/iucv/af_iucv.c:150 No description found for return value of 'iucv_sock_in_state'
> Warning: net/iucv/af_iucv.c:163 No description found for return value of 'iucv_below_msglim'
> Warning: net/iucv/af_iucv.c:889 No description found for return value of 'iucv_send_iprm'
> 
> Our team will fix those, unless you want to add them to this patch.

Please go ahead with those fixes.
Thanks.

-- 
~Randy