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
