Re: [RFC PATCH 3/5] kobject: Fix kernel-doc comment first line

["Tobin C. Harding" <me@tobin.cc>]

On Fri, May 03, 2019 at 09:56:07AM +0200, Johan Hovold wrote:
> On Fri, May 03, 2019 at 11:40:15AM +1000, Tobin C. Harding wrote:
> > On Thu, May 02, 2019 at 10:39:22AM +0200, Johan Hovold wrote:
> > > On Thu, May 02, 2019 at 06:25:39PM +1000, Tobin C. Harding wrote: > Adding Jon to CC
> > > > 
> > > > On Thu, May 02, 2019 at 09:38:23AM +0200, Johan Hovold wrote:
> > > > > On Thu, May 02, 2019 at 12:31:40PM +1000, Tobin C. Harding wrote:
> > > > > > kernel-doc comments have a prescribed format.  This includes parenthesis
> > > > > > on the function name.  To be _particularly_ correct we should also
> > > > > > capitalise the brief description and terminate it with a period.
> > > > > 
> > > > > Why do think capitalisation and full stop is required for the function
> > > > > description?
> > > > > 
> > > > > Sure, the example in the current doc happen to use that, but I'm not
> > > > > sure that's intended as a prescription.
> > > > > 
> > > > > The old kernel-doc nano-HOWTO specifically did not use this:
> > > > > 
> > > > > 	https://www.kernel.org/doc/Documentation/kernel-doc-nano-HOWTO.txt
> > > > > 
> > > > 
> > > > Oh?  I was basing this on Documentation/doc-guide/kernel-doc.rst
> > > > 
> > > > 	Function documentation
> > > > 	----------------------
> > > > 
> > > > 	The general format of a function and function-like macro kernel-doc comment is::
> > > > 
> > > > 	  /**
> > > > 	   * function_name() - Brief description of function.
> > > > 	   * @arg1: Describe the first argument.
> > > > 	   * @arg2: Describe the second argument.
> > > > 	   *        One can provide multiple line descriptions
> > > > 	   *        for arguments.
> > > > 
> > > > I figured that was the canonical way to do kernel-doc function
> > > > comments.  I have however refrained from capitalising and adding the
> > > > period to argument strings to reduce code churn.  I figured if I'm
> > > > touching the line to add parenthesis then I might as well make it
> > > > perfect (if such a thing exists).
> > >
> > > I think you may have read too much into that example. Many of the
> > > current function and parameter descriptions aren't even full sentences,
> > > so sentence case and full stop doesn't really make any sense.
> > >
> > > Looks like we discussed this last fall as well:
> > 
> > Ha, this was funny.  By 'we' at first I thought you meant 'we the kernel
> > community' but you actually meant we as in 'me and you'.  Clearly you
> > failed to convince me last time :)
> > 
> > > 	https://lkml.kernel.org/r/20180912093116.GC1089@localhost
> > 
> > I am totally aware this is close to code churn and any discussion is
> > bikeshedding ... for me just because loads of places don't do this it
> > still looks nicer to my eyes
> > 
> > /**
> > * sfn() - Super awesome function.
> > 
> > than
> > 
> > /**
> > */ sfn() - super awesome function
> > 
> > I most likely will keep doing these changes if I am touching the
> > kernel-doc comments for other reasons and then drop the changes if the
> > subsystem maintainer thinks its code churn.
> > 
> > I defiantly won't do theses changes in GNSS, GREYBUS, or USB SERIAL.
> 
> This isn't about any particular subsystem, but more the tendency of
> people to make up random rules and try to to force it on others. It's
> churn, and also makes things like code forensics and backports harder
> for no good reason.

Points noted.

> Both capitalisation styles are about as common for the function
> description judging from a quick grep, but only 10% or so use a full
> stop ('.'). And forcing the use of sentence case and full stop for
> things like
> 
> 	/**
> 	 * maar_init() - Initialise MAARs.
> 
> or
> 
> 	* @instr: Operational instruction.
> 
> would be not just ugly, but wrong (as these are not independent
> clauses).

You are correct here.

Thanks for taking the time to flesh out your argument Johan, I am now in
agreement with you :)

Cheers,
Tobin.