HID: uclogic: kernel-doc fixes for uclogic_params_* functions
Subsystems (2)
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 Dumpdrivers/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 twodrivers/hid/hid-uclogic-params.c:80: warning: missing initial short description on line:
* Dump tablet interface frame parameters with hid_dbg(), indented with twodrivers/hid/hid-uclogic-params.c:80: info: Scanning doc for function Dumpdrivers/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].
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
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.
--- drivers/hid/hid-uclogic-params.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
drivers/hid/hid-uclogic-params.c +3 -3
@@ -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
Jonathan Corbet
maintainerRe: [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(), anduclogic_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")Reported-by kernel test robot <[email protected]>Cc Nikolai Kondrashov <[email protected]>Cc Jiri Kosina <[email protected]>Cc Benjamin Tissoires <[email protected]>Cc "José Expósito" <[email protected]>Signed-off-by Bagas Sanjaya <[email protected]>--- drivers/hid/hid-uclogic-params.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)drivers/hid/hid-uclogic-params.c +0
-0
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
PATCH 2/2 HID: uclogic: add missing function name in uclogic_params_hid_dbg() kernel-doc comment
In reply to Bagas Sanjayauclogic_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.
--- drivers/hid/hid-uclogic-params.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/hid/hid-uclogic-params.c +1 -1
@@ -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