[PATCH 0/2] module: add/fix 'kernel-doc' comments

[PATCH 0/2] module: add/fix 'kernel-doc' comments

[Sergey Shtylyov]

Here are 2 patches against the 'modules-next' branch of Jessica Yu's 'linux.git' repo.
I'm cleaning up the 'kernel-doc' function comments...

[1/2] module: fix up 'kernel-doc' comments
[2/2] module: add more 'kernel-doc' comments

[PATCH 1/2] module: fix up 'kernel-doc' comments

[Sergey Shtylyov]

Some 'kernel-doc' function comments do not fully comply with the specified
format due to:

- missing () after the function name;

- "RETURNS:"/"Returns:" instead of "Return:" when documenting the function's
  result.

- empty line before describing the function's arguments.

Signed-off-by: Sergey Shtylyov <s.shtylyov@omprussia.ru>

---
 kernel/module.c |   10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

Index: linux/kernel/module.c
===================================================================
--- linux.orig/kernel/module.c
+++ linux/kernel/module.c
@@ -727,13 +727,12 @@ bool __is_module_percpu_address(unsigned
 }
 
 /**
- * is_module_percpu_address - test whether address is from module static percpu
+ * is_module_percpu_address() - test whether address is from module static percpu
  * @addr: address to test
  *
  * Test whether @addr belongs to module static percpu area.
  *
- * RETURNS:
- * %true if @addr is from module static percpu area
+ * Return: %true if @addr is from module static percpu area
  */
 bool is_module_percpu_address(unsigned long addr)
 {
@@ -957,11 +956,10 @@ static int try_stop_module(struct module
 }
 
 /**
- * module_refcount - return the refcount or -1 if unloading
- *
+ * module_refcount() - return the refcount or -1 if unloading
  * @mod:	the module we're checking
  *
- * Returns:
+ * Return:
  *	-1 if the module is in the process of unloading
  *	otherwise the number of references in the kernel to the module
  */

[PATCH 2/2] module: add more 'kernel-doc' comments

[Sergey Shtylyov]

Some functions have the proper 'kernel-doc' comments but these don't start
with proper /** -- fix that, along with adding () to the function name on
the following lines to fully comply with the 'kernel-doc' format.

Signed-off-by: Sergey Shtylyov <s.shtylyov@omprussia.ru>

---
 kernel/module.c |   16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

Index: linux/kernel/module.c
===================================================================
--- linux.orig/kernel/module.c
+++ linux/kernel/module.c
@@ -4491,8 +4491,8 @@ out:
 	return e;
 }
 
-/*
- * is_module_address - is this address inside a module?
+/**
+ * is_module_address() - is this address inside a module?
  * @addr: the address to check.
  *
  * See is_module_text_address() if you simply want to see if the address
@@ -4509,8 +4509,8 @@ bool is_module_address(unsigned long add
 	return ret;
 }
 
-/*
- * __module_address - get the module which contains an address.
+/**
+ * __module_address() - get the module which contains an address.
  * @addr: the address.
  *
  * Must be called with preempt disabled or module mutex held so that
@@ -4534,8 +4534,8 @@ struct module *__module_address(unsigned
 	return mod;
 }
 
-/*
- * is_module_text_address - is this address inside module code?
+/**
+ * is_module_text_address() - is this address inside module code?
  * @addr: the address to check.
  *
  * See is_module_address() if you simply want to see if the address is
@@ -4553,8 +4553,8 @@ bool is_module_text_address(unsigned lon
 	return ret;
 }
 
-/*
- * __module_text_address - get the module whose code contains an address.
+/**
+ * __module_text_address() - get the module whose code contains an address.
  * @addr: the address.
  *
  * Must be called with preempt disabled or module mutex held so that

Re: [PATCH 0/2] module: add/fix 'kernel-doc' comments

[Jessica Yu]

+++ Sergey Shtylyov [04/11/20 23:33 +0300]:
>Here are 2 patches against the 'modules-next' branch of Jessica Yu's 'linux.git' repo.
>I'm cleaning up the 'kernel-doc' function comments...
>
>[1/2] module: fix up 'kernel-doc' comments
>[2/2] module: add more 'kernel-doc' comments

Applied, thanks!

Jessica