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

[Jani Nikula <jani.nikula@linux.intel.com>]

Hi, just a couple of drive-by comments.

On Thu, 02 Apr 2020, Ricardo Cañuelo <ricardo.canuelo@collabora.com> wrote:
> +Function reference
> +==================
> +
> +.. kernel-doc:: kernel/printk/printk.c
> +   :functions: printk
> +
> +.. kernel-doc:: include/linux/printk.h
> +   :functions: pr_emerg
> +
> +.. kernel-doc:: include/linux/printk.h
> +   :functions: pr_alert
> +
> +.. kernel-doc:: include/linux/printk.h
> +   :functions: pr_crit
> +
> +.. kernel-doc:: include/linux/printk.h
> +   :functions: pr_err
> +
> +.. kernel-doc:: include/linux/printk.h
> +   :functions: pr_warn
> +
> +.. kernel-doc:: include/linux/printk.h
> +   :functions: pr_notice
> +
> +.. kernel-doc:: include/linux/printk.h
> +   :functions: pr_info
> +
> +.. kernel-doc:: include/linux/printk.h
> +   :functions: pr_fmt
> +
> +.. kernel-doc:: include/linux/printk.h
> +   :functions: pr_debug
> +
> +.. kernel-doc:: include/linux/printk.h
> +   :functions: pr_devel
> +
> +.. kernel-doc:: include/linux/printk.h
> +   :functions: pr_cont

: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.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Graphics Center