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@xxxxxxxxxxxxxxxx>
Acked-by: Richard Cochran <richardcochran@xxxxxxxxx>
Acked-by: Sergey Ryazanov <ryazanov.s.a@xxxxxxxxx>
Reviewed-by: Edward Cree <ecree.xilinx@xxxxxxxxx>
Acked-by: Alexandra Winter <wintera@xxxxxxxxxxxxx>
Signed-off-by: Jakub Kicinski <kuba@xxxxxxxxxx>
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);
