[ PATCH ] Documentation: fixed doc-build warnings

[ PATCH ] Documentation: fixed doc-build warnings

[kushagra765]

From 9a9918b051d5709b5e14ca8afa29f3ef644b8688 Mon Sep 17 00:00:00 2001
From: Kushagra Verma <kushagra765@outlook.com>
Date: Sat, 26 Mar 2022 16:43:15 +0530
Subject: [PATCH] Documentation: fixed doc-build warnings

   This patch fixes the following (and 2 other) doc-build warnings:
      1. ./include/linux/dcache.h:308: warning: expecting prototype for dget, dget_dlock(). Prototype was for dget_dlock() instead

      2. ./include/linux/fscache.h:268: warning: Excess function parameter 'object' description in 'fscache_use_cookie'

      3 ./include/linux/fscache.h:285: warning: Excess function parameter 'object' description in 'fscache_unuse_cookie'

      4. ./drivers/gpu/drm/drm_format_helper.c:640: warning: Excess function parameter 'src' description in 'drm_fb_xrgb8888_to_mono_reversed'

Signed-off-by: Kushagra Verma <kushagra765@outlook.com>
---
 drivers/gpu/drm/drm_format_helper.c | 1 -
 drivers/usb/dwc3/core.c             | 1 -
 drivers/usb/dwc3/gadget.c           | 3 +--
 include/linux/dcache.h              | 2 +-
 include/linux/fscache.h             | 2 --
 5 files changed, 2 insertions(+), 7 deletions(-)

diff --git a/drivers/gpu/drm/drm_format_helper.c b/drivers/gpu/drm/drm_format_helper.c
index bc0f49773868..d753b34950c9 100644
--- a/drivers/gpu/drm/drm_format_helper.c
+++ b/drivers/gpu/drm/drm_format_helper.c
@@ -624,7 +624,6 @@ static void drm_fb_gray8_to_mono_reversed_line(u8 *dst, const u8 *src, unsigned
  * drm_fb_xrgb8888_to_mono_reversed - Convert XRGB8888 to reversed monochrome
  * @dst: reversed monochrome destination buffer
  * @dst_pitch: Number of bytes between two consecutive scanlines within dst
- * @src: XRGB8888 source buffer
  * @fb: DRM framebuffer
  * @clip: Clip rectangle area to copy
  *
diff --git a/drivers/usb/dwc3/core.c b/drivers/usb/dwc3/core.c
index f4c09951b517..63e2ccbb7c33 100644
--- a/drivers/usb/dwc3/core.c
+++ b/drivers/usb/dwc3/core.c
@@ -343,7 +343,6 @@ static void dwc3_frame_length_adjustment(struct dwc3 *dwc)
  *		from the default, this will set clock period in DWC3_GUCTL
  *		register.
  * @dwc: Pointer to our controller context structure
- * @ref_clk_per: reference clock period in ns
  */
 static void dwc3_ref_clk_period(struct dwc3 *dwc)
 {
diff --git a/drivers/usb/dwc3/gadget.c b/drivers/usb/dwc3/gadget.c
index a0c883f19a41..ee98004434df 100644
--- a/drivers/usb/dwc3/gadget.c
+++ b/drivers/usb/dwc3/gadget.c
@@ -660,7 +660,6 @@ static void dwc3_stop_active_transfer(struct dwc3_ep *dep, bool force,
 /**
  * dwc3_gadget_calc_tx_fifo_size - calculates the txfifo size value
  * @dwc: pointer to the DWC3 context
- * @nfifos: number of fifos to calculate for
  *
  * Calculates the size value based on the equation below:
  *
@@ -693,7 +692,7 @@ static int dwc3_gadget_calc_tx_fifo_size(struct dwc3 *dwc, int mult)
 }
 
 /**
- * dwc3_gadget_clear_tx_fifo_size - Clears txfifo allocation
+ * dwc3_gadget_clear_tx_fifos - Clears txfifo allocation
  * @dwc: pointer to the DWC3 context
  *
  * Iterates through all the endpoint registers and clears the previous txfifo
diff --git a/include/linux/dcache.h b/include/linux/dcache.h
index f5bba51480b2..fa35ac489a42 100644
--- a/include/linux/dcache.h
+++ b/include/linux/dcache.h
@@ -297,7 +297,7 @@ extern char *dentry_path(const struct dentry *, char *, int);
 /* Allocation counts.. */
 
 /**
- *	dget, dget_dlock -	get a reference to a dentry
+ *	dget_dlock - get a reference to a dentry
  *	@dentry: dentry to get a reference to
  *
  *	Given a dentry or %NULL pointer increment the reference count
diff --git a/include/linux/fscache.h b/include/linux/fscache.h
index d44ff747a657..9e29494241ea 100644
--- a/include/linux/fscache.h
+++ b/include/linux/fscache.h
@@ -256,7 +256,6 @@ struct fscache_cookie *fscache_acquire_cookie(struct fscache_volume *volume,
 
 /**
  * fscache_use_cookie - Request usage of cookie attached to an object
- * @object: Object description
  * @will_modify: If cache is expected to be modified locally
  *
  * Request usage of the cookie attached to an object.  The caller should tell
@@ -272,7 +271,6 @@ static inline void fscache_use_cookie(struct fscache_cookie *cookie,
 
 /**
  * fscache_unuse_cookie - Cease usage of cookie attached to an object
- * @object: Object description
  * @aux_data: Updated auxiliary data (or NULL)
  * @object_size: Revised size of the object (or NULL)
  *
-- 
2.25.1

Re: [ PATCH ] Documentation: fixed doc-build warnings

[Greg KH]

On Sat, Mar 26, 2022 at 05:22:55PM +0530, kushagra765@outlook.com wrote:
> >From 9a9918b051d5709b5e14ca8afa29f3ef644b8688 Mon Sep 17 00:00:00 2001
> From: Kushagra Verma <kushagra765@outlook.com>
> Date: Sat, 26 Mar 2022 16:43:15 +0530
> Subject: [PATCH] Documentation: fixed doc-build warnings

This should not be in the body of the email, please fix :(

> 
>    This patch fixes the following (and 2 other) doc-build warnings:
>       1. ./include/linux/dcache.h:308: warning: expecting prototype for dget, dget_dlock(). Prototype was for dget_dlock() instead
> 
>       2. ./include/linux/fscache.h:268: warning: Excess function parameter 'object' description in 'fscache_use_cookie'
> 
>       3 ./include/linux/fscache.h:285: warning: Excess function parameter 'object' description in 'fscache_unuse_cookie'
> 
>       4. ./drivers/gpu/drm/drm_format_helper.c:640: warning: Excess function parameter 'src' description in 'drm_fb_xrgb8888_to_mono_reversed'

This needs to be split up into one-patch-per-subsystem and can not be
taken as-is.

thanks,

greg k-h

Re: [ PATCH ] Documentation: fixed doc-build warnings

[David Howells]

kushagra765@outlook.com wrote:

> @@ -256,7 +256,6 @@ struct fscache_cookie *fscache_acquire_cookie(struct fscache_volume *volume,
>  
>  /**
>   * fscache_use_cookie - Request usage of cookie attached to an object
> - * @object: Object description
>   * @will_modify: If cache is expected to be modified locally
>   *
>   * Request usage of the cookie attached to an object.  The caller should tell
> @@ -272,7 +271,6 @@ static inline void fscache_use_cookie(struct fscache_cookie *cookie,
>  
>  /**
>   * fscache_unuse_cookie - Cease usage of cookie attached to an object
> - * @object: Object description
>   * @aux_data: Updated auxiliary data (or NULL)
>   * @object_size: Revised size of the object (or NULL)
>   *

Just deleting these lines is the wrong thing to do.  They should instead
mention the cookie parameter.

David