On 5/2/19 6:40 PM, 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. > > Oh, and I'm totally going to CC you know every time I flick one of these > patches, prepare to get spammed :)
I have seen this discussion before also. And sometimes it is not even a discussion -- it's more of an edict. To which I object/disagree. The current (or past) comment style is perfectly fine IMO. No caps needed. No ending '.' needed. -- ~Randy
