Skip to contentSkip to conversation

HID: uclogic: kernel-doc fixes for uclogic_params_* functions

PATCH In review Bagas Sanjaya 2 participants 4 messages May 28, 2022 – May 29, 2022

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

cover HID: uclogic: kernel-doc fixes for uclogic_params_* functions

Running kernel-doc script on drivers/hid/hid-uclogic-params.c found these 6 warnings below:

drivers/hid/hid-uclogic-params.c:48: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* Dump tablet interface pen parameters with hid_dbg(), indented with one tab.
drivers/hid/hid-uclogic-params.c:48: warning: missing initial short description on line:
* Dump tablet interface pen parameters with hid_dbg(), indented with one tab.
drivers/hid/hid-uclogic-params.c:48: info: Scanning doc for function Dump
drivers/hid/hid-uclogic-params.c:80: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* Dump tablet interface frame parameters with hid_dbg(), indented with two
drivers/hid/hid-uclogic-params.c:80: warning: missing initial short description on line:
* Dump tablet interface frame parameters with hid_dbg(), indented with two
drivers/hid/hid-uclogic-params.c:80: info: Scanning doc for function Dump
drivers/hid/hid-uclogic-params.c:105: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* Dump tablet interface parameters with hid_dbg().
drivers/hid/hid-uclogic-params.c:105: warning: missing initial short description on line:
* Dump tablet interface parameters with hid_dbg().

One of them is reported by kernel test robot at kernel test robot at [1].

[1]: https://lore.kernel.org/linux-doc/[email protected]/

Fix these warnings by remove extraneous asterisk on static function comments on patch [1/2] and add missing function name for void function on patch [2/2].

Cc Nikolai Kondrashov <[email protected]>
Cc Jiri Kosina <[email protected]>
Cc Benjamin Tissoires <[email protected]>
Cc "José Expósito" <[email protected]>

Bagas Sanjaya (2):
HID: uclogic: remove extraneous asterisk on uclogic_params_* static
functions comments
HID: uclogic: add missing function name in uclogic_params_hid_dbg()
kernel-doc comment

 drivers/hid/hid-uclogic-params.c | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

base-commit: bf272460d744112bacd4c4d562592decbf0edf64

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#1 lore raw

PATCH 1/2 HID: uclogic: remove extraneous asterisk on uclogic_params_* static functions comments

*uclogic_params_pen_inrange_to_str(), uclogic_params_pen_hid_dbg(), and uclogic_params_frame_hid_dbg() are static functions but contain double-asterisk (/** */) comment, which confuses kernel-doc as public function for generating documentation.

Remove the extraneous asterisk from these comments.

Fixes a228809fa6f39c ("HID: uclogic: Move param printing to a function")
Cc Nikolai Kondrashov <[email protected]>
Cc Jiri Kosina <[email protected]>
Cc Benjamin Tissoires <[email protected]>
Cc "José Expósito" <[email protected]>
---
 drivers/hid/hid-uclogic-params.c | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
drivers/hid/hid-uclogic-params.c +3 -3
index db838f16282d64..71501453de12e4 100644
@@ -20,7 +20,7 @@
 #include <linux/ctype.h>
 #include <asm/unaligned.h>
 
-/**
+/*
  * uclogic_params_pen_inrange_to_str() - Convert a pen in-range reporting type
  *                                       to a string.
  *
@@ -44,7 +44,7 @@ static const char *uclogic_params_pen_inrange_to_str(
 	}
 }
 
-/**
+/*
  * Dump tablet interface pen parameters with hid_dbg(), indented with one tab.
  *
  * @hdev:	The HID device the pen parameters describe.
@@ -76,7 +76,7 @@ static void uclogic_params_pen_hid_dbg(const struct hid_device *hdev,
 		(pen->tilt_y_flipped ? "true" : "false"));
 }
 
-/**
+/*
  * Dump tablet interface frame parameters with hid_dbg(), indented with two
  * tabs.
  *
Signature · 1 line
An old man doll... just what I always wanted! - Clara
maintainer
#2 lore raw

Re: [PATCH 1/2] HID: uclogic: remove extraneous asterisk on uclogic_params_* static functions comments

Quoted 6 lines · Bagas Sanjaya

*uclogic_params_pen_inrange_to_str(), uclogic_params_pen_hid_dbg(), and uclogic_params_frame_hid_dbg() are static functions but contain double-asterisk (/** */) comment, which confuses kernel-doc as public function for generating documentation.

Remove the extraneous asterisk from these comments.

So there is nothing wrong with making kerneldoc comments for static functions, that is not where the problem lies.

Quoted 20 lines
Fixes a228809fa6f39c ("HID: uclogic: Move param printing to a function")
Cc Nikolai Kondrashov <[email protected]>
Cc Jiri Kosina <[email protected]>
Cc Benjamin Tissoires <[email protected]>
Cc "José Expósito" <[email protected]>
---
 drivers/hid/hid-uclogic-params.c | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
drivers/hid/hid-uclogic-params.c +0 -0
index db838f16282d64..71501453de12e4 100644

drivers/hid/hid-uclogic-params.c line 26

Quoted 8 lines
drivers/hid/hid-uclogic-params.c +1 -1
@@ -20,7 +20,7 @@
 #include <linux/ctype.h>
 #include <asm/unaligned.h>
 
-/**
+/*
  * uclogic_params_pen_inrange_to_str() - Convert a pen in-range reporting type
  *                                       to a string.
  *

A more likely problem here is the blank between the function intro and the parameter description.

drivers/hid/hid-uclogic-params.c static const char *uclogic_params_pen_inrange_to_str( · line 49

Quoted 8 lines
drivers/hid/hid-uclogic-params.c +1 -1
@@ -44,7 +44,7 @@ static const char *uclogic_params_pen_inrange_to_str(
 	}
 }
 
-/**
+/*
  * Dump tablet interface pen parameters with hid_dbg(), indented with one tab.
  *

Here too

drivers/hid/hid-uclogic-params.c static void uclogic_params_pen_hid_dbg(const struct hid_device *hdev, · line 82

Quoted 10 lines
drivers/hid/hid-uclogic-params.c +1 -1
  * @hdev:	The HID device the pen parameters describe.
@@ -76,7 +76,7 @@ static void uclogic_params_pen_hid_dbg(const struct hid_device *hdev,
 		(pen->tilt_y_flipped ? "true" : "false"));
 }
 
-/**
+/*
  * Dump tablet interface frame parameters with hid_dbg(), indented with two
  * tabs.
  *

Here, instead, this needs to be formatted as a proper kerneldoc comment with the function name.

jon

#3 lore raw

PATCH 2/2 HID: uclogic: add missing function name in uclogic_params_hid_dbg() kernel-doc comment

In reply to Bagas Sanjaya

uclogic_params_hid_dbg() is public void function. The comment for kernel-doc, however, lack its function name on short description, thus triggers "missing initial short description" warning.

Add the function name to fix the warning.

Fixes a228809fa6f39c ("HID: uclogic: Move param printing to a function")
Cc Nikolai Kondrashov <[email protected]>
Cc Jiri Kosina <[email protected]>
Cc Benjamin Tissoires <[email protected]>
Cc "José Expósito" <[email protected]>
---
 drivers/hid/hid-uclogic-params.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/hid/hid-uclogic-params.c +1 -1
index 71501453de12e4..0319e3f1527f1d 100644
@@ -102,7 +102,7 @@ static void uclogic_params_frame_hid_dbg(
 }
 
 /**
- * Dump tablet interface parameters with hid_dbg().
+ * uclogic_params_hid_dbg - Dump tablet interface parameters with hid_dbg().
  *
  * @hdev:	The HID device the parameters describe.
  * @params:	The parameters to dump.
Signature · 1 line
An old man doll... just what I always wanted! - Clara