netdev - Re: [PATCH net-next v2] net: reformat kdoc return statements

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] [thread-next>] [day] [month] [year] [list]

Message-ID: <a1a7c865-be0a-4071-a50a-7c15d7b8b095@intel.com>
Date: Fri, 6 Dec 2024 16:08:42 +0100
From: Przemek Kitszel <przemyslaw.kitszel@...el.com>
To: Jakub Kicinski <kuba@...nel.org>, <davem@...emloft.net>
CC: <netdev@...r.kernel.org>, <edumazet@...gle.com>, <pabeni@...hat.com>,
	Johannes Berg <johannes@...solutions.net>, Richard Cochran
	<richardcochran@...il.com>, Sergey Ryazanov <ryazanov.s.a@...il.com>, "Edward
 Cree" <ecree.xilinx@...il.com>, Alexandra Winter <wintera@...ux.ibm.com>,
	<pablo@...filter.org>, <loic.poulain@...aro.org>, <dsahern@...nel.org>,
	<hawk@...nel.org>, <ilias.apalodimas@...aro.org>, <jhs@...atatu.com>,
	<jiri@...nulli.us>, <netfilter-devel@...r.kernel.org>,
	<linux-wireless@...r.kernel.org>, Jonathan Corbet <corbet@....net>
Subject: Re: [PATCH net-next v2] net: reformat kdoc return statements

On 12/5/24 17:59, Jakub Kicinski wrote:
> kernel-doc -Wall warns about missing Return: statement for non-void
> functions. We have a number of kdocs in our headers which are missing
> the colon, IOW they use
>   * Return some value
> or
>   * Returns some value
> 
> Having the colon makes some sense, it should help kdoc parser avoid
> false positives. So add them. This is mostly done with a sed script,
> and removing the unnecessary cases (mostly the comments which aren't
> kdoc).
> 
> Acked-by: Johannes Berg <johannes@...solutions.net>
> Acked-by: Richard Cochran <richardcochran@...il.com>
> Acked-by: Sergey Ryazanov <ryazanov.s.a@...il.com>
> Reviewed-by: Edward Cree <ecree.xilinx@...il.com>
> Acked-by: Alexandra Winter <wintera@...ux.ibm.com>
> Signed-off-by: Jakub Kicinski <kuba@...nel.org>

Thank you!
I put some comments, but not about your patch, rather a general
observations

> ---

> - * Return number of phc vclocks
> + * Return: number of phc vclocks

so good that there is no enforcement for the final dot (.)

>    */
>   int ethtool_get_phc_vclocks(struct net_device *dev, int **vclock_index);
>   
> @@ -1253,7 +1253,7 @@ static inline int ethtool_mm_frag_size_min_to_add(u32 val_min, u32 *val_add,
>    * ethtool_get_ts_info_by_layer - Obtains time stamping capabilities from the MAC or PHY layer.
>    * @dev: pointer to net_device structure
>    * @info: buffer to hold the result
> - * Returns zero on success, non-zero otherwise.
> + * Returns: zero on success, non-zero otherwise.

As kdoc-warn-free code becomes fashionable, I tend to see more and more
shortcuts for the obvious cases, like here. To the point of:
  * Return: zero or errno.
or even:
  * Return: errno

I have no problem with that, perhaps only that we loose two lines for
such trivial stuff. I know you could also add a special param:
* @return: errno

Would be good to know if anyone have an opinion (that is going
to enforce at some point) about the boundary on accepted laziness.

>    */
>   int ethtool_get_ts_info_by_layer(struct net_device *dev,
>   				 struct kernel_ethtool_ts_info *info);