[PATCH] rtl8723bs: Add kernel-doc comment for rtw_reset_continual_io_error in rtw_io.c

[PATCH] rtl8723bs: Add kernel-doc comment for rtw_reset_continual_io_error in rtw_io.c

[cjz]

From: changjunzheng <guagua210311@qq.com>

rtw_reset_continual_io_error lacks a standard kernel-doc comment and has an incorrect
parameter name (dvobjprive vs dvobj) in the existing comment, which causes gcc W=1
warning and reduces code readability.

This change replaces the non-standard comment with a complete English kernel-doc comment,
fixes the parameter name error, and keeps all functional logic unchanged.

Signed-off-by: changjunzheng <guagua210311@qq.com>
---
 drivers/staging/rtl8723bs/core/rtw_io.c | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/drivers/staging/rtl8723bs/core/rtw_io.c b/drivers/staging/rtl8723bs/core/rtw_io.c
index fe9f94001eed..358a16b25a20 100644
--- a/drivers/staging/rtl8723bs/core/rtw_io.c
+++ b/drivers/staging/rtl8723bs/core/rtw_io.c
@@ -147,7 +147,15 @@ int rtw_inc_and_chk_continual_io_error(struct dvobj_priv *dvobj)
 	return false;
 }
 
-/* Set the continual_io_error of this @param dvobjprive to 0 */
+/**
+ * rtw_reset_continual_io_error - Reset the continual IO error counter to zero
+ * @dvobj: Pointer to the device object private data structure
+ *
+ * Atomically set the 'continual_io_error' atomic counter in the dvobj private data
+ * structure to zero, resetting the state of consecutive IO error counting for the device.
+ *
+ * Return: None
+ */
 void rtw_reset_continual_io_error(struct dvobj_priv *dvobj)
 {
 	atomic_set(&dvobj->continual_io_error, 0);
-- 
2.43.0

Re: [PATCH] rtl8723bs: Add kernel-doc comment for rtw_reset_continual_io_error in rtw_io.c

[Greg KH]

On Sun, Dec 14, 2025 at 02:16:59PM +0800, cjz wrote:
> From: changjunzheng <guagua210311@qq.com>
> 
> rtw_reset_continual_io_error lacks a standard kernel-doc comment and has an incorrect
> parameter name (dvobjprive vs dvobj) in the existing comment, which causes gcc W=1
> warning and reduces code readability.
> 
> This change replaces the non-standard comment with a complete English kernel-doc comment,
> fixes the parameter name error, and keeps all functional logic unchanged.
> 
> Signed-off-by: changjunzheng <guagua210311@qq.com>
> ---
>  drivers/staging/rtl8723bs/core/rtw_io.c | 10 +++++++++-
>  1 file changed, 9 insertions(+), 1 deletion(-)
> 
> diff --git a/drivers/staging/rtl8723bs/core/rtw_io.c b/drivers/staging/rtl8723bs/core/rtw_io.c
> index fe9f94001eed..358a16b25a20 100644
> --- a/drivers/staging/rtl8723bs/core/rtw_io.c
> +++ b/drivers/staging/rtl8723bs/core/rtw_io.c
> @@ -147,7 +147,15 @@ int rtw_inc_and_chk_continual_io_error(struct dvobj_priv *dvobj)
>  	return false;
>  }
>  
> -/* Set the continual_io_error of this @param dvobjprive to 0 */
> +/**
> + * rtw_reset_continual_io_error - Reset the continual IO error counter to zero
> + * @dvobj: Pointer to the device object private data structure
> + *
> + * Atomically set the 'continual_io_error' atomic counter in the dvobj private data
> + * structure to zero, resetting the state of consecutive IO error counting for the device.
> + *
> + * Return: None
> + */
>  void rtw_reset_continual_io_error(struct dvobj_priv *dvobj)
>  {
>  	atomic_set(&dvobj->continual_io_error, 0);
> -- 
> 2.43.0
> 

None of the functions in this file are in kernel doc format, so why do
it for just this one?  Does it get added to the kernel documentation
output when it is generated?  If not, I wouldn't worry about it at all.


Also, an atomic variable is a huge hint that maybe this function is
doing something wrong, why does this need to be an atomic at all?

thanks,

greg k-h

Re: [PATCH] rtl8723bs: Add kernel-doc comment for rtw_reset_continual_io_error in rtw_io.c

[Jeff Johnson]

On 12/13/2025 10:16 PM, cjz wrote:
> From: changjunzheng <guagua210311@qq.com>
> 
> rtw_reset_continual_io_error lacks a standard kernel-doc comment and has an incorrect
> parameter name (dvobjprive vs dvobj) in the existing comment, which causes gcc W=1
> warning and reduces code readability.
> 
> This change replaces the non-standard comment with a complete English kernel-doc comment,
> fixes the parameter name error, and keeps all functional logic unchanged.

In addition to Greg's comment, please also review:

https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes

In particular:
Describe your changes in imperative mood, e.g. “make xyzzy do frotz” instead
of “[This patch] makes xyzzy do frotz” or “[I] changed xyzzy to do frotz”, as
if you are giving orders to the codebase to change its behaviour.