[v2] drm: fix parameters documentation style
diff mbox series

Message ID 20200114160135.14990-1-benjamin.gaignard@st.com
State New
Headers show
Series
  • [v2] drm: fix parameters documentation style
Related show

Commit Message

Benjamin Gaignard Jan. 14, 2020, 4:01 p.m. UTC
Remove old documentation style and use new one to avoid warnings when
compiling with W=1

Signed-off-by: Benjamin Gaignard <benjamin.gaignard@st.com>
---
CC: Randy Dunlap <rdunlap@infradead.org>
version 2:
- fix return documentation

 drivers/gpu/drm/drm_dma.c | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)

Comments

Sam Ravnborg Jan. 18, 2020, 9:41 a.m. UTC | #1
Hi Benjamin

On Tue, Jan 14, 2020 at 05:01:35PM +0100, Benjamin Gaignard wrote:
> Remove old documentation style and use new one to avoid warnings when
> compiling with W=1
> 
> Signed-off-by: Benjamin Gaignard <benjamin.gaignard@st.com>

Thanks for the warning fixes.
This is legacy stuff that is not even wired into the kernel-doc stuff.
But that is no excuse for old-style comments.

Applied to drm-misc-next.

	Sam

> ---
> CC: Randy Dunlap <rdunlap@infradead.org>
> version 2:
> - fix return documentation
> 
>  drivers/gpu/drm/drm_dma.c | 21 +++++++++++----------
>  1 file changed, 11 insertions(+), 10 deletions(-)
> 
> diff --git a/drivers/gpu/drm/drm_dma.c b/drivers/gpu/drm/drm_dma.c
> index e45b07890c5a..a7add55a85b4 100644
> --- a/drivers/gpu/drm/drm_dma.c
> +++ b/drivers/gpu/drm/drm_dma.c
> @@ -42,10 +42,10 @@
>  #include "drm_legacy.h"
>  
>  /**
> - * Initialize the DMA data.
> + * drm_legacy_dma_setup() - Initialize the DMA data.
>   *
> - * \param dev DRM device.
> - * \return zero on success or a negative value on failure.
> + * @dev: DRM device.
> + * Return: zero on success or a negative value on failure.
>   *
>   * Allocate and initialize a drm_device_dma structure.
>   */
> @@ -71,9 +71,9 @@ int drm_legacy_dma_setup(struct drm_device *dev)
>  }
>  
>  /**
> - * Cleanup the DMA resources.
> + * drm_legacy_dma_takedown() - Cleanup the DMA resources.
>   *
> - * \param dev DRM device.
> + * @dev: DRM device.
>   *
>   * Free all pages associated with DMA buffers, the buffers and pages lists, and
>   * finally the drm_device::dma structure itself.
> @@ -120,10 +120,10 @@ void drm_legacy_dma_takedown(struct drm_device *dev)
>  }
>  
>  /**
> - * Free a buffer.
> + * drm_legacy_free_buffer() - Free a buffer.
>   *
> - * \param dev DRM device.
> - * \param buf buffer to free.
> + * @dev: DRM device.
> + * @buf: buffer to free.
>   *
>   * Resets the fields of \p buf.
>   */
> @@ -139,9 +139,10 @@ void drm_legacy_free_buffer(struct drm_device *dev, struct drm_buf * buf)
>  }
>  
>  /**
> - * Reclaim the buffers.
> + * drm_legacy_reclaim_buffers() - Reclaim the buffers.
>   *
> - * \param file_priv DRM file private.
> + * @dev: DRM device.
> + * @file_priv: DRM file private.
>   *
>   * Frees each buffer associated with \p file_priv not already on the hardware.
>   */
> -- 
> 2.15.0
> 
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel
Benjamin Gaignard Jan. 20, 2020, 8:11 a.m. UTC | #2
On 1/18/20 10:41 AM, Sam Ravnborg wrote:
> Hi Benjamin
>
> On Tue, Jan 14, 2020 at 05:01:35PM +0100, Benjamin Gaignard wrote:
>> Remove old documentation style and use new one to avoid warnings when
>> compiling with W=1
>>
>> Signed-off-by: Benjamin Gaignard <benjamin.gaignard@st.com>
> Thanks for the warning fixes.
> This is legacy stuff that is not even wired into the kernel-doc stuff.
> But that is no excuse for old-style comments.

There is still quite a few of them in other drm files (drm_context.c,  
drm_bufs.c, drm_vm.c, drm_lock.c)

but I don't know how to fix them. Your advices are welcome.

Benjamin

>
> Applied to drm-misc-next.
>
> 	Sam
>
>> ---
>> CC: Randy Dunlap <rdunlap@infradead.org>
>> version 2:
>> - fix return documentation
>>
>>   drivers/gpu/drm/drm_dma.c | 21 +++++++++++----------
>>   1 file changed, 11 insertions(+), 10 deletions(-)
>>
>> diff --git a/drivers/gpu/drm/drm_dma.c b/drivers/gpu/drm/drm_dma.c
>> index e45b07890c5a..a7add55a85b4 100644
>> --- a/drivers/gpu/drm/drm_dma.c
>> +++ b/drivers/gpu/drm/drm_dma.c
>> @@ -42,10 +42,10 @@
>>   #include "drm_legacy.h"
>>   
>>   /**
>> - * Initialize the DMA data.
>> + * drm_legacy_dma_setup() - Initialize the DMA data.
>>    *
>> - * \param dev DRM device.
>> - * \return zero on success or a negative value on failure.
>> + * @dev: DRM device.
>> + * Return: zero on success or a negative value on failure.
>>    *
>>    * Allocate and initialize a drm_device_dma structure.
>>    */
>> @@ -71,9 +71,9 @@ int drm_legacy_dma_setup(struct drm_device *dev)
>>   }
>>   
>>   /**
>> - * Cleanup the DMA resources.
>> + * drm_legacy_dma_takedown() - Cleanup the DMA resources.
>>    *
>> - * \param dev DRM device.
>> + * @dev: DRM device.
>>    *
>>    * Free all pages associated with DMA buffers, the buffers and pages lists, and
>>    * finally the drm_device::dma structure itself.
>> @@ -120,10 +120,10 @@ void drm_legacy_dma_takedown(struct drm_device *dev)
>>   }
>>   
>>   /**
>> - * Free a buffer.
>> + * drm_legacy_free_buffer() - Free a buffer.
>>    *
>> - * \param dev DRM device.
>> - * \param buf buffer to free.
>> + * @dev: DRM device.
>> + * @buf: buffer to free.
>>    *
>>    * Resets the fields of \p buf.
>>    */
>> @@ -139,9 +139,10 @@ void drm_legacy_free_buffer(struct drm_device *dev, struct drm_buf * buf)
>>   }
>>   
>>   /**
>> - * Reclaim the buffers.
>> + * drm_legacy_reclaim_buffers() - Reclaim the buffers.
>>    *
>> - * \param file_priv DRM file private.
>> + * @dev: DRM device.
>> + * @file_priv: DRM file private.
>>    *
>>    * Frees each buffer associated with \p file_priv not already on the hardware.
>>    */
>> -- 
>> 2.15.0
>>
>> _______________________________________________
>> dri-devel mailing list
>> dri-devel@lists.freedesktop.org
>> https://lists.freedesktop.org/mailman/listinfo/dri-devel
Sam Ravnborg Jan. 20, 2020, 8:21 p.m. UTC | #3
Hi Benjamin.

On Mon, Jan 20, 2020 at 08:11:01AM +0000, Benjamin GAIGNARD wrote:
> 
> On 1/18/20 10:41 AM, Sam Ravnborg wrote:
> > Hi Benjamin
> >
> > On Tue, Jan 14, 2020 at 05:01:35PM +0100, Benjamin Gaignard wrote:
> >> Remove old documentation style and use new one to avoid warnings when
> >> compiling with W=1
> >>
> >> Signed-off-by: Benjamin Gaignard <benjamin.gaignard@st.com>
> > Thanks for the warning fixes.
> > This is legacy stuff that is not even wired into the kernel-doc stuff.
> > But that is no excuse for old-style comments.
> 
> There is still quite a few of them in other drm files (drm_context.c,  
> drm_bufs.c, drm_vm.c, drm_lock.c)
> 
> but I don't know how to fix them. Your advices are welcome.

I have no strong opinion on way forward here.
But if someone (you?) type the patches and they are even acked,
we should not ignore them.

	Sam

Patch
diff mbox series

diff --git a/drivers/gpu/drm/drm_dma.c b/drivers/gpu/drm/drm_dma.c
index e45b07890c5a..a7add55a85b4 100644
--- a/drivers/gpu/drm/drm_dma.c
+++ b/drivers/gpu/drm/drm_dma.c
@@ -42,10 +42,10 @@ 
 #include "drm_legacy.h"
 
 /**
- * Initialize the DMA data.
+ * drm_legacy_dma_setup() - Initialize the DMA data.
  *
- * \param dev DRM device.
- * \return zero on success or a negative value on failure.
+ * @dev: DRM device.
+ * Return: zero on success or a negative value on failure.
  *
  * Allocate and initialize a drm_device_dma structure.
  */
@@ -71,9 +71,9 @@  int drm_legacy_dma_setup(struct drm_device *dev)
 }
 
 /**
- * Cleanup the DMA resources.
+ * drm_legacy_dma_takedown() - Cleanup the DMA resources.
  *
- * \param dev DRM device.
+ * @dev: DRM device.
  *
  * Free all pages associated with DMA buffers, the buffers and pages lists, and
  * finally the drm_device::dma structure itself.
@@ -120,10 +120,10 @@  void drm_legacy_dma_takedown(struct drm_device *dev)
 }
 
 /**
- * Free a buffer.
+ * drm_legacy_free_buffer() - Free a buffer.
  *
- * \param dev DRM device.
- * \param buf buffer to free.
+ * @dev: DRM device.
+ * @buf: buffer to free.
  *
  * Resets the fields of \p buf.
  */
@@ -139,9 +139,10 @@  void drm_legacy_free_buffer(struct drm_device *dev, struct drm_buf * buf)
 }
 
 /**
- * Reclaim the buffers.
+ * drm_legacy_reclaim_buffers() - Reclaim the buffers.
  *
- * \param file_priv DRM file private.
+ * @dev: DRM device.
+ * @file_priv: DRM file private.
  *
  * Frees each buffer associated with \p file_priv not already on the hardware.
  */