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). thanks, Tobin.
