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.
