diff mbox series

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

Message ID 20201206190247.1861316-3-sam@ravnborg.org (mailing list archive)
State Superseded, archived
Headers show
Series drivers/video: W=1 warning fixes | expand

Commit Message

Sam Ravnborg Dec. 6, 2020, 7:02 p.m. UTC
Fix kernel-doc warnings reported when using W=1

v2:
  - Improve subject (Lee)

v3:
  - Add RETURNS documentation (Thomas)

Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
Cc: Lee Jones <lee.jones@linaro.org>
Cc: Sam Ravnborg <sam@ravnborg.org>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: "Alexander A. Klimov" <grandmaster@al2klimov.de>
---
 drivers/video/fbdev/core/fb_notify.c | 10 ++++++++++
 drivers/video/fbdev/core/fbmon.c     |  2 +-
 2 files changed, 11 insertions(+), 1 deletion(-)

Comments

Randy Dunlap Dec. 6, 2020, 7:37 p.m. UTC | #1
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@ravnborg.org>
> Cc: Lee Jones <lee.jones@linaro.org>
> Cc: Sam Ravnborg <sam@ravnborg.org>
> Cc: Randy Dunlap <rdunlap@infradead.org>
> Cc: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
> Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
> Cc: "Alexander A. Klimov" <grandmaster@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
>   *
Sam Ravnborg Dec. 6, 2020, 8:52 p.m. UTC | #2
Hi Randy.

On Sun, Dec 06, 2020 at 11:37:17AM -0800, Randy Dunlap wrote:
> 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)
OK, like this?
I did not fix any existing uses of RETURNS, thats for another patch.

	Sam

commit 03b7c3ecf7cb51b5429ca0ef58a32bb4dc486610
Author: Sam Ravnborg <sam@ravnborg.org>
Date:   Sat Nov 28 23:40:49 2020 +0100

    video: fbdev: core: Fix kernel-doc warnings in fbmon + fb_notify
    
    Fix kernel-doc warnings reported when using W=1
    
    v2:
      - Improve subject (Lee)
    
    v3:
      - Add RETURNS documentation (Thomas)
    
    v4:
      - Use Return: not RETURNS (Randy)
    
    Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
    Cc: Lee Jones <lee.jones@linaro.org>
    Cc: Sam Ravnborg <sam@ravnborg.org>
    Cc: Randy Dunlap <rdunlap@infradead.org>
    Cc: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
    Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
    Cc: "Alexander A. Klimov" <grandmaster@al2klimov.de>

diff --git a/drivers/video/fbdev/core/fb_notify.c b/drivers/video/fbdev/core/fb_notify.c
index 74c2da528884..10e3b9a74adc 100644
--- a/drivers/video/fbdev/core/fb_notify.c
+++ b/drivers/video/fbdev/core/fb_notify.c
@@ -19,6 +19,8 @@ static BLOCKING_NOTIFIER_HEAD(fb_notifier_list);
 /**
  *	fb_register_client - register a client notifier
  *	@nb: notifier block to callback on events
+ *
+ *	Return: 0 on success, negative error code on failure.
  */
 int fb_register_client(struct notifier_block *nb)
 {
@@ -29,6 +31,8 @@ EXPORT_SYMBOL(fb_register_client);
 /**
  *	fb_unregister_client - unregister a client notifier
  *	@nb: notifier block to callback on events
+ *
+ *	Return: 0 on success, negative error code on failure.
  */
 int fb_unregister_client(struct notifier_block *nb)
 {
@@ -38,7 +42,10 @@ EXPORT_SYMBOL(fb_unregister_client);
 
 /**
  * fb_notifier_call_chain - notify clients of fb_events
+ * @val: value passed to callback
+ * @v: pointer passed to callback
  *
+ * Return: 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
  *
@@ -1100,7 +1101,6 @@ static u32 fb_get_hblank_by_hfreq(u32 hfreq, u32 xres)
  *                                    2 * M
  *        M = 300;
  *        C = 30;
-
  */
 static u32 fb_get_hblank_by_dclk(u32 dclk, u32 xres)
 {
Randy Dunlap Dec. 6, 2020, 9:27 p.m. UTC | #3
On 12/6/20 12:52 PM, Sam Ravnborg wrote:
> Hi Randy.
> 
> On Sun, Dec 06, 2020 at 11:37:17AM -0800, Randy Dunlap wrote:
>> 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)
> OK, like this?

Yes. LGTM.

Acked-by: Randy Dunlap <rdunlap@infradead.org>

> I did not fix any existing uses of RETURNS, thats for another patch.
> 
> 	Sam
> 
> commit 03b7c3ecf7cb51b5429ca0ef58a32bb4dc486610
> Author: Sam Ravnborg <sam@ravnborg.org>
> Date:   Sat Nov 28 23:40:49 2020 +0100
> 
>     video: fbdev: core: Fix kernel-doc warnings in fbmon + fb_notify
>     
>     Fix kernel-doc warnings reported when using W=1
>     
>     v2:
>       - Improve subject (Lee)
>     
>     v3:
>       - Add RETURNS documentation (Thomas)
>     
>     v4:
>       - Use Return: not RETURNS (Randy)
>     
>     Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
>     Cc: Lee Jones <lee.jones@linaro.org>
>     Cc: Sam Ravnborg <sam@ravnborg.org>
>     Cc: Randy Dunlap <rdunlap@infradead.org>
>     Cc: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
>     Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
>     Cc: "Alexander A. Klimov" <grandmaster@al2klimov.de>
Thomas Zimmermann Dec. 7, 2020, 8:16 a.m. UTC | #4
Hi

Am 06.12.20 um 20:37 schrieb 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)

Thanks for the note. I asked for RETURNS: because the rest of the file 
appears to be using it. Returns: is certainly the better alternative. I 
didn't know there was a difference.

Best regards
Thomas

> 
> 
>> Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
>> Cc: Lee Jones <lee.jones@linaro.org>
>> Cc: Sam Ravnborg <sam@ravnborg.org>
>> Cc: Randy Dunlap <rdunlap@infradead.org>
>> Cc: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
>> Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
>> Cc: "Alexander A. Klimov" <grandmaster@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 Dunlap Dec. 7, 2020, 4:43 p.m. UTC | #5
On 12/7/20 12:16 AM, Thomas Zimmermann wrote:
> Hi
> 
> Am 06.12.20 um 20:37 schrieb 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)
> 
> Thanks for the note. I asked for RETURNS: because the rest of the file appears to be using it. Returns: is certainly the better alternative. I didn't know there was a difference.
> 
> Best regards
> Thomas
> 

I'm not insisting on using Return:
It can stay the same as the rest of the file IMO.

>>
>>
>>> Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
>>> Cc: Lee Jones <lee.jones@linaro.org>
>>> Cc: Sam Ravnborg <sam@ravnborg.org>
>>> Cc: Randy Dunlap <rdunlap@infradead.org>
>>> Cc: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
>>> Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
>>> Cc: "Alexander A. Klimov" <grandmaster@al2klimov.de>
>>> ---
>>>   drivers/video/fbdev/core/fb_notify.c | 10 ++++++++++
>>>   drivers/video/fbdev/core/fbmon.c     |  2 +-
>>>   2 files changed, 11 insertions(+), 1 deletion(-)
Sam Ravnborg Dec. 7, 2020, 5:12 p.m. UTC | #6
Hi Randy,
> >>
> >> 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)
> > 
> > Thanks for the note. I asked for RETURNS: because the rest of the file appears to be using it. Returns: is certainly the better alternative. I didn't know there was a difference.
> > 
> > Best regards
> > Thomas
> > 
> 
> I'm not insisting on using Return:
> It can stay the same as the rest of the file IMO.

fb_notify.c contains only the three functions modified in this patch.

So it is consistent within this file, but other fbdev/core/ files uses
RETURNS. git grep shows 5 hits only.

So we will stick with the documented practice here.

	Sam
diff mbox series

Patch

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
  *
@@ -1100,7 +1101,6 @@  static u32 fb_get_hblank_by_hfreq(u32 hfreq, u32 xres)
  *                                    2 * M
  *        M = 300;
  *        C = 30;
-
  */
 static u32 fb_get_hblank_by_dclk(u32 dclk, u32 xres)
 {