Skip to contentSkip to conversation

drm: fix parameters documentation style

PATCH Applied Benjamin Gaignard 3 participants 5 messages Jan 14, 2020 – Jan 20, 2020

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 drm: fix parameters documentation style

Remove old documentation style and use new one to avoid warnings when compiling with W=1

---
CC: Randy Dunlap <[email protected]>
version 2:
- fix return documentation

 drivers/gpu/drm/drm_dma.c | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)
drivers/gpu/drm/drm_dma.c +11 -10
index e45b07890c5a..a7add55a85b4 100644
@@ -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.
  */
Signature · 1 line
2.15.0
Acked-by on v2 1/1
#1 lore raw
Quoted 4 lines · Benjamin Gaignard

Remove old documentation style and use new one to avoid warnings when compiling with W=1

Looks good. Thanks.

Quoted 66 lines

---
CC: Randy Dunlap <[email protected]>
version 2:
- fix return documentation

 drivers/gpu/drm/drm_dma.c | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)
drivers/gpu/drm/drm_dma.c +11 -10
index e45b07890c5a..a7add55a85b4 100644
@@ -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.
  */
Signature · 2 lines
~Randy
Reported-by: Randy Dunlap <[email protected]>
Applied
#2 lore raw
In reply to Benjamin Gaignard

Hi Benjamin

Quoted 4 lines · Benjamin Gaignard

Remove old documentation style and use new one to avoid warnings when compiling with W=1

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

Quoted 72 lines

---
CC: Randy Dunlap <[email protected]>
version 2:
- fix return documentation

 drivers/gpu/drm/drm_dma.c | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)
drivers/gpu/drm/drm_dma.c +11 -10
index e45b07890c5a..a7add55a85b4 100644
@@ -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.
  */
Signature · 6 lines
2.15.0

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

#3 lore raw
Quoted 10 lines · Sam Ravnborg

Hi Benjamin

Quoted 4 lines · Benjamin Gaignard

Remove old documentation style and use new one to avoid warnings when compiling with W=1

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

Quoted 77 lines

Applied to drm-misc-next.

Sam

Quoted 72 lines

---
CC: Randy Dunlap <[email protected]>
version 2:
- fix return documentation

  drivers/gpu/drm/drm_dma.c | 21 +++++++++++----------
  1 file changed, 11 insertions(+), 10 deletions(-)
drivers/gpu/drm/drm_dma.c +11 -10
index e45b07890c5a..a7add55a85b4 100644
@@ -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.
   */
Signature · 6 lines
2.15.0

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
#4 lore raw

Hi Benjamin.

Quoted 9 lines · Benjamin GAIGNARD
Quoted 7 lines · Sam Ravnborg

Hi Benjamin

Quoted 4 lines · Benjamin Gaignard

Remove old documentation style and use new one to avoid warnings when compiling with W=1

Quoted 8 lines
Quoted 3 lines

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