Re: [PATCH v2] docs: pr_*() kerneldocs and basic printk docs

["Ricardo Cañuelo" <ricardo.canuelo@collabora.com>]

On Fri, 2020-04-03 at 09:17 +0300, Jani Nikula wrote:
> :functions: lets you specify multiple space separated identifiers. You
> could have *one* kernel-doc directive, and list all the functions you
> want. What you have above causes printk.h to be parsed 11 times.
> 
> Did not actually check, but I think the only difference is that listing
> multiple identifiers produces the documentation in the order it occurs
> in the file.
> 
> > +/**
> > + * pr_emerg - Print an emergency-level message
> > + * @fmt: format string
> > + *
> > + * This macro expands to a printk with KERN_EMERG loglevel. It uses
> > pr_fmt() to
> > + * generate the format string.
> >   */
> >  #define pr_emerg(fmt, ...) \
> >  	printk(KERN_EMERG pr_fmt(fmt), ##__VA_ARGS__)
> 
> Doesn't this produce a warning for not documenting varargs? That would
> be @...: in the comment.

Hi Jani, thanks for your comments.

You're right. Initially I had all the :functions: statements separate because I
intended to have the function references interspersed between the document
paragraphs, but since I finally decided to put them all at the bottom it'd be
better to group them as much as possible.

Regarding the varargs doc, I'm getting no warnings. At first I included the @...
for every function and then I noticed some other existing cases where they were
automatically generated even though they weren't explicitly documented, so I
though that was the way to go.

But now that you mention it, there's this in Documentation/doc-guide/kernel-
doc.rst:

    If a function has a variable number of arguments, its description should
    be written in kernel-doc notation as::

          * @...: description

so I'll go ahead and add them.

Best,
Ricardo