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

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

[Jakub Kicinski]

On Sat, 16 Nov 2024 16:23:59 +0000 Russell King (Oracle) wrote:
> On Fri, Nov 15, 2024 at 08:36:12AM -0800, 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).  
> 
> I wonder about this... I suspect it's going to be a constant battle to
> ensure that docs use Return: or Returns: because it's not "natural"
> when writing documentation.
> 
> Maybe the tooling should accept a sentence starting "Return(s?)" and
> convert it to "Return(s):" in generated documentation?

I missed this merge window, so we have time, let's ask Jon.

Jon, do you have a preference on making the kernel-doc formatting
accept "* Return" without the colon? vs fixing all the mis-formatting?
Looks like we have roughly 100 of those in networking headers 
(just counting those under include/).

FWIW we catch new instances of the missing return problem, so it
shouldn't be getting worse.

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

[Jonathan Corbet]

Jakub Kicinski <kuba@kernel.org> writes:

> On Sat, 16 Nov 2024 16:23:59 +0000 Russell King (Oracle) wrote:
>> On Fri, Nov 15, 2024 at 08:36:12AM -0800, 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).  
>> 
>> I wonder about this... I suspect it's going to be a constant battle to
>> ensure that docs use Return: or Returns: because it's not "natural"
>> when writing documentation.
>> 
>> Maybe the tooling should accept a sentence starting "Return(s?)" and
>> convert it to "Return(s):" in generated documentation?
>
> I missed this merge window, so we have time, let's ask Jon.
>
> Jon, do you have a preference on making the kernel-doc formatting
> accept "* Return" without the colon? vs fixing all the mis-formatting?
> Looks like we have roughly 100 of those in networking headers 
> (just counting those under include/).

I guess my preference would be to fix the comments and keep the tighter
rule for the format.  It's not something I feel hugely strongly about,
though, so I don't think I would try to block an attempt to go the other
way.

Thanks,

jon