[PATCH v3 02/13] video: fbdev: core: Fix kernel-doc warnings in fbmon + fb_notify

[Randy Dunlap]

On 12/6/20 11:02 AM, Sam Ravnborg wrote:
> Fix kernel-doc warnings reported when using W=1
> 
> v2:
>   - Improve subject (Lee)
> 
> v3:
>   - Add RETURNS documentation (Thomas)

Hi Sam,

Yes, RETURNS: will work. It just looks like any kernel-doc section name,
such as Context: or Note:.
However, the documented format for return info is "Return:".
(see Documentation/doc-guide/kernel-doc.rst)


> Signed-off-by: Sam Ravnborg <sam at ravnborg.org>
> Cc: Lee Jones <lee.jones at linaro.org>
> Cc: Sam Ravnborg <sam at ravnborg.org>
> Cc: Randy Dunlap <rdunlap at infradead.org>
> Cc: Bartlomiej Zolnierkiewicz <b.zolnierkie at samsung.com>
> Cc: Daniel Vetter <daniel.vetter at ffwll.ch>
> Cc: "Alexander A. Klimov" <grandmaster at al2klimov.de>
> ---
>  drivers/video/fbdev/core/fb_notify.c | 10 ++++++++++
>  drivers/video/fbdev/core/fbmon.c     |  2 +-
>  2 files changed, 11 insertions(+), 1 deletion(-)
> 
> diff --git a/drivers/video/fbdev/core/fb_notify.c b/drivers/video/fbdev/core/fb_notify.c
> index 74c2da528884..4e39c61fae1f 100644
> --- a/drivers/video/fbdev/core/fb_notify.c
> +++ b/drivers/video/fbdev/core/fb_notify.c
> @@ -19,6 +19,9 @@ static BLOCKING_NOTIFIER_HEAD(fb_notifier_list);
>  /**
>   *	fb_register_client - register a client notifier
>   *	@nb: notifier block to callback on events
> + *
> + *	RETURNS:
> + *	0 on success, negative error code on failure.
>   */
>  int fb_register_client(struct notifier_block *nb)
>  {
> @@ -29,6 +32,9 @@ EXPORT_SYMBOL(fb_register_client);
>  /**
>   *	fb_unregister_client - unregister a client notifier
>   *	@nb: notifier block to callback on events
> + *
> + *	RETURNS:
> + *	0 on success, negative error code on failure.
>   */
>  int fb_unregister_client(struct notifier_block *nb)
>  {
> @@ -38,7 +44,11 @@ EXPORT_SYMBOL(fb_unregister_client);
>  
>  /**
>   * fb_notifier_call_chain - notify clients of fb_events
> + * @val: value passed to callback
> + * @v: pointer passed to callback
>   *
> + * RETURNS:
> + * The return value of the last notifier function
>   */
>  int fb_notifier_call_chain(unsigned long val, void *v)
>  {
> diff --git a/drivers/video/fbdev/core/fbmon.c b/drivers/video/fbdev/core/fbmon.c
> index 1bf82dbc9e3c..b0e690f41025 100644
> --- a/drivers/video/fbdev/core/fbmon.c
> +++ b/drivers/video/fbdev/core/fbmon.c
> @@ -605,6 +605,7 @@ static void get_detailed_timing(unsigned char *block,
>   * fb_create_modedb - create video mode database
>   * @edid: EDID data
>   * @dbsize: database size
> + * @specs: monitor specifications, may be NULL
>   *
>   * RETURNS: struct fb_videomode, @dbsize contains length of database
>   *


-- 
~Randy