diff mbox series

most: fix kernel-doc warnings

Message ID 20230113063947.23174-1-rdunlap@infradead.org
State New
Headers
Series most: fix kernel-doc warnings |

Commit Message

Randy Dunlap Jan. 13, 2023, 6:39 a.m. UTC 
  Fix various W=1 kernel-doc warnings in drivers/most/:

drivers/most/most_usb.c:669: warning: Excess function parameter 'data' description in 'link_stat_timer_handler'
drivers/most/most_usb.c:769: warning: cannot understand function prototype: 'const struct file_operations hdm_usb_fops = '
drivers/most/most_usb.c:776: warning: cannot understand function prototype: 'const struct usb_device_id usbid[] = '
drivers/most/most_cdev.c:301: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * Initialization of struct file_operations
drivers/most/most_cdev.c:414: warning: Function parameter or member 'args' not described in 'comp_probe'
drivers/most/most_snd.c:56: warning: Function parameter or member 'pcm_hardware' not described in 'channel'
drivers/most/most_snd.c:56: warning: Function parameter or member 'copy_fn' not described in 'channel'
drivers/most/most_snd.c:404: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * Initialization of struct snd_pcm_ops
drivers/most/most_snd.c:514: warning: Function parameter or member 'device_name' not described in 'audio_probe_channel'
drivers/most/most_snd.c:703: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * Initialization of the struct most_component


Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Christian Gromm <christian.gromm@microchip.com>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
---
Also: what does MOST mean? Can that be added to drivers/most/Kconfig,
    in a prompt or help text?
Also: how about a MAINTAINERS entry for drivers/most/?

 drivers/most/most_cdev.c |    5 +++--
 drivers/most/most_snd.c  |   10 ++++++----
 drivers/most/most_usb.c  |    6 +++---
 3 files changed, 12 insertions(+), 9 deletions(-)

Comments

Greg KH Jan. 19, 2023, 4:15 p.m. UTC | #1 
On Thu, Jan 12, 2023 at 10:39:47PM -0800, Randy Dunlap wrote:
> Fix various W=1 kernel-doc warnings in drivers/most/:
> 
> drivers/most/most_usb.c:669: warning: Excess function parameter 'data' description in 'link_stat_timer_handler'
> drivers/most/most_usb.c:769: warning: cannot understand function prototype: 'const struct file_operations hdm_usb_fops = '
> drivers/most/most_usb.c:776: warning: cannot understand function prototype: 'const struct usb_device_id usbid[] = '
> drivers/most/most_cdev.c:301: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * Initialization of struct file_operations
> drivers/most/most_cdev.c:414: warning: Function parameter or member 'args' not described in 'comp_probe'
> drivers/most/most_snd.c:56: warning: Function parameter or member 'pcm_hardware' not described in 'channel'
> drivers/most/most_snd.c:56: warning: Function parameter or member 'copy_fn' not described in 'channel'
> drivers/most/most_snd.c:404: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * Initialization of struct snd_pcm_ops
> drivers/most/most_snd.c:514: warning: Function parameter or member 'device_name' not described in 'audio_probe_channel'
> drivers/most/most_snd.c:703: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * Initialization of the struct most_component
> 
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Christian Gromm <christian.gromm@microchip.com>
> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> ---
> Also: what does MOST mean? Can that be added to drivers/most/Kconfig,
>     in a prompt or help text?
> Also: how about a MAINTAINERS entry for drivers/most/?

That would be good, Christian, can you send a patch for that?

thanks,

greg k-h
Christian.Gromm@microchip.com Jan. 23, 2023, 10:31 a.m. UTC | #2 
On Thu, 2023-01-19 at 17:15 +0100, Greg Kroah-Hartman wrote:
> EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
> 
> On Thu, Jan 12, 2023 at 10:39:47PM -0800, Randy Dunlap wrote:
> > Fix various W=1 kernel-doc warnings in drivers/most/:
> >
> > drivers/most/most_usb.c:669: warning: Excess function parameter 'data' description in 'link_stat_timer_handler'
> > drivers/most/most_usb.c:769: warning: cannot understand function prototype: 'const struct file_operations hdm_usb_fops = '
> > drivers/most/most_usb.c:776: warning: cannot understand function prototype: 'const struct usb_device_id usbid[] = '
> > drivers/most/most_cdev.c:301: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> >  * Initialization of struct file_operations
> > drivers/most/most_cdev.c:414: warning: Function parameter or member 'args' not described in 'comp_probe'
> > drivers/most/most_snd.c:56: warning: Function parameter or member 'pcm_hardware' not described in 'channel'
> > drivers/most/most_snd.c:56: warning: Function parameter or member 'copy_fn' not described in 'channel'
> > drivers/most/most_snd.c:404: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> >  * Initialization of struct snd_pcm_ops
> > drivers/most/most_snd.c:514: warning: Function parameter or member 'device_name' not described in 'audio_probe_channel'
> > drivers/most/most_snd.c:703: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> >  * Initialization of the struct most_component
> >
> >
> > Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> > Cc: Christian Gromm <christian.gromm@microchip.com>
> > Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> > ---
> > Also: what does MOST mean? Can that be added to drivers/most/Kconfig,
> >     in a prompt or help text?
> > Also: how about a MAINTAINERS entry for drivers/most/?
> 
> That would be good, Christian, can you send a patch for that?
> 

Sure, I can do that. But since I am not working for the automotive divison
within the company anymore I need to indentify the right person for that first.

thnaks,
Chris

> thanks,
> 
> greg k-h
Greg KH Jan. 31, 2023, 9:46 a.m. UTC | #3 
On Mon, Jan 23, 2023 at 10:31:56AM +0000, Christian.Gromm@microchip.com wrote:
> 
> On Thu, 2023-01-19 at 17:15 +0100, Greg Kroah-Hartman wrote:
> > EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
> > 
> > On Thu, Jan 12, 2023 at 10:39:47PM -0800, Randy Dunlap wrote:
> > > Fix various W=1 kernel-doc warnings in drivers/most/:
> > >
> > > drivers/most/most_usb.c:669: warning: Excess function parameter 'data' description in 'link_stat_timer_handler'
> > > drivers/most/most_usb.c:769: warning: cannot understand function prototype: 'const struct file_operations hdm_usb_fops = '
> > > drivers/most/most_usb.c:776: warning: cannot understand function prototype: 'const struct usb_device_id usbid[] = '
> > > drivers/most/most_cdev.c:301: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> > >  * Initialization of struct file_operations
> > > drivers/most/most_cdev.c:414: warning: Function parameter or member 'args' not described in 'comp_probe'
> > > drivers/most/most_snd.c:56: warning: Function parameter or member 'pcm_hardware' not described in 'channel'
> > > drivers/most/most_snd.c:56: warning: Function parameter or member 'copy_fn' not described in 'channel'
> > > drivers/most/most_snd.c:404: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> > >  * Initialization of struct snd_pcm_ops
> > > drivers/most/most_snd.c:514: warning: Function parameter or member 'device_name' not described in 'audio_probe_channel'
> > > drivers/most/most_snd.c:703: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> > >  * Initialization of the struct most_component
> > >
> > >
> > > Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> > > Cc: Christian Gromm <christian.gromm@microchip.com>
> > > Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> > > ---
> > > Also: what does MOST mean? Can that be added to drivers/most/Kconfig,
> > >     in a prompt or help text?
> > > Also: how about a MAINTAINERS entry for drivers/most/?
> > 
> > That would be good, Christian, can you send a patch for that?
> > 
> 
> Sure, I can do that. But since I am not working for the automotive divison
> within the company anymore I need to indentify the right person for that first.

Should we just remove these files if no one is using them anymore and
there's no one to maintain them?

thanks,

greg k-h
Christian.Gromm@microchip.com Feb. 2, 2023, 8:16 a.m. UTC | #4 
On Tue, 2023-01-31 at 10:46 +0100, Greg KH wrote:
> EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
> 
> On Mon, Jan 23, 2023 at 10:31:56AM +0000, Christian.Gromm@microchip.com wrote:
> >
> > On Thu, 2023-01-19 at 17:15 +0100, Greg Kroah-Hartman wrote:
> > > EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
> > >
> > > On Thu, Jan 12, 2023 at 10:39:47PM -0800, Randy Dunlap wrote:
> > > > Fix various W=1 kernel-doc warnings in drivers/most/:
> > > >
> > > > drivers/most/most_usb.c:669: warning: Excess function parameter 'data' description in 'link_stat_timer_handler'
> > > > drivers/most/most_usb.c:769: warning: cannot understand function prototype: 'const struct file_operations hdm_usb_fops = '
> > > > drivers/most/most_usb.c:776: warning: cannot understand function prototype: 'const struct usb_device_id usbid[] = '
> > > > drivers/most/most_cdev.c:301: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> > > >  * Initialization of struct file_operations
> > > > drivers/most/most_cdev.c:414: warning: Function parameter or member 'args' not described in 'comp_probe'
> > > > drivers/most/most_snd.c:56: warning: Function parameter or member 'pcm_hardware' not described in 'channel'
> > > > drivers/most/most_snd.c:56: warning: Function parameter or member 'copy_fn' not described in 'channel'
> > > > drivers/most/most_snd.c:404: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> > > >  * Initialization of struct snd_pcm_ops
> > > > drivers/most/most_snd.c:514: warning: Function parameter or member 'device_name' not described in 'audio_probe_channel'
> > > > drivers/most/most_snd.c:703: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> > > >  * Initialization of the struct most_component
> > > >
> > > >
> > > > Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> > > > Cc: Christian Gromm <christian.gromm@microchip.com>
> > > > Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> > > > ---
> > > > Also: what does MOST mean? Can that be added to drivers/most/Kconfig,
> > > >     in a prompt or help text?
> > > > Also: how about a MAINTAINERS entry for drivers/most/?
> > >
> > > That would be good, Christian, can you send a patch for that?
> > >
> >
> > Sure, I can do that. But since I am not working for the automotive divison
> > within the company anymore I need to indentify the right person for that first.
> 
> Should we just remove these files if no one is using them anymore and
> there's no one to maintain them?
> 
No, the files should not be removed. We will come up with a maintainer shortly.

thanks,
Chris 


> thanks,
> 
> greg k-h
Christian.Gromm@microchip.com Feb. 7, 2023, 2:04 p.m. UTC | #5 
On Tue, 2023-01-31 at 10:46 +0100, Greg KH wrote:
> EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
> 
> On Mon, Jan 23, 2023 at 10:31:56AM +0000, Christian.Gromm@microchip.com wrote:
> >
> > On Thu, 2023-01-19 at 17:15 +0100, Greg Kroah-Hartman wrote:
> > > EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
> > >
> > > On Thu, Jan 12, 2023 at 10:39:47PM -0800, Randy Dunlap wrote:
> > > > Fix various W=1 kernel-doc warnings in drivers/most/:
> > > >
> > > > drivers/most/most_usb.c:669: warning: Excess function parameter 'data' description in 'link_stat_timer_handler'
> > > > drivers/most/most_usb.c:769: warning: cannot understand function prototype: 'const struct file_operations hdm_usb_fops = '
> > > > drivers/most/most_usb.c:776: warning: cannot understand function prototype: 'const struct usb_device_id usbid[] = '
> > > > drivers/most/most_cdev.c:301: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> > > >  * Initialization of struct file_operations
> > > > drivers/most/most_cdev.c:414: warning: Function parameter or member 'args' not described in 'comp_probe'
> > > > drivers/most/most_snd.c:56: warning: Function parameter or member 'pcm_hardware' not described in 'channel'
> > > > drivers/most/most_snd.c:56: warning: Function parameter or member 'copy_fn' not described in 'channel'
> > > > drivers/most/most_snd.c:404: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> > > >  * Initialization of struct snd_pcm_ops
> > > > drivers/most/most_snd.c:514: warning: Function parameter or member 'device_name' not described in 'audio_probe_channel'
> > > > drivers/most/most_snd.c:703: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> > > >  * Initialization of the struct most_component
> > > >
> > > >
> > > > Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> > > > Cc: Christian Gromm <christian.gromm@microchip.com>
> > > > Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> > > > ---
> > > > Also: what does MOST mean? Can that be added to drivers/most/Kconfig,
> > > >     in a prompt or help text?
> > > > Also: how about a MAINTAINERS entry for drivers/most/?
> > >
> > > That would be good, Christian, can you send a patch for that?
> > >
> >
> > Sure, I can do that. But since I am not working for the automotive divison
> > within the company anymore I need to indentify the right person for that first.
> 
> Should we just remove these files if no one is using them anymore and
> there's no one to maintain them?
> 

Parthiban Veerasooran <parthiban.veerasooran@microchip.com> will be maintaining the MOST driver.
He will submit the patch to add the MAINTAINERS entry.

> thanks,
> 
> greg k-h
diff mbox series

Patch

diff -- a/drivers/most/most_usb.c b/drivers/most/most_usb.c
--- a/drivers/most/most_usb.c
+++ b/drivers/most/most_usb.c
@@ -660,7 +660,7 @@  static void hdm_request_netinfo(struct m
 
 /**
  * link_stat_timer_handler - schedule work obtaining mac address and link status
- * @data: pointer to USB device instance
+ * @t: pointer to timer_list which holds a pointer to the USB device instance
  *
  * The handler runs in interrupt context. That's why we need to defer the
  * tasks to a work queue.
@@ -763,14 +763,14 @@  static void wq_clear_halt(struct work_st
 	mutex_unlock(&mdev->io_mutex);
 }
 
-/**
+/*
  * hdm_usb_fops - file operation table for USB driver
  */
 static const struct file_operations hdm_usb_fops = {
 	.owner = THIS_MODULE,
 };
 
-/**
+/*
  * usb_device_id - ID table for HCD device probing
  */
 static const struct usb_device_id usbid[] = {
diff -- a/drivers/most/most_cdev.c b/drivers/most/most_cdev.c
--- a/drivers/most/most_cdev.c
+++ b/drivers/most/most_cdev.c
@@ -297,7 +297,7 @@  static __poll_t comp_poll(struct file *f
 	return mask;
 }
 
-/**
+/*
  * Initialization of struct file_operations
  */
 static const struct file_operations channel_fops = {
@@ -404,8 +404,9 @@  static int comp_tx_completion(struct mos
  * @channel_id: channel index/ID
  * @cfg: pointer to actual channel configuration
  * @name: name of the device to be created
+ * @args: pointer to array of component parameters (from configfs)
  *
- * This allocates achannel object and creates the device node in /dev
+ * This allocates a channel object and creates the device node in /dev
  *
  * Returns 0 on success or error code otherwise.
  */
diff -- a/drivers/most/most_snd.c b/drivers/most/most_snd.c
--- a/drivers/most/most_snd.c
+++ b/drivers/most/most_snd.c
@@ -27,6 +27,7 @@  static struct most_component comp;
 /**
  * struct channel - private structure to keep channel specific data
  * @substream: stores the substream structure
+ * @pcm_hardware: low-level hardware description
  * @iface: interface for which the channel belongs to
  * @cfg: channel configuration
  * @card: registered sound card
@@ -38,6 +39,7 @@  static struct most_component comp;
  * @opened: set when the stream is opened
  * @playback_task: playback thread
  * @playback_waitq: waitq used by playback thread
+ * @copy_fn: copy function for PCM-specific format and width
  */
 struct channel {
 	struct snd_pcm_substream *substream;
@@ -400,7 +402,7 @@  static snd_pcm_uframes_t pcm_pointer(str
 	return channel->buffer_pos;
 }
 
-/**
+/*
  * Initialization of struct snd_pcm_ops
  */
 static const struct snd_pcm_ops pcm_ops = {
@@ -501,8 +503,8 @@  static void release_adapter(struct sound
  * @iface: pointer to interface instance
  * @channel_id: channel index/ID
  * @cfg: pointer to actual channel configuration
- * @arg_list: string that provides the name of the device to be created in /dev
- *	      plus the desired audio resolution
+ * @device_name: name of the device to be created in /dev
+ * @arg_list: string that provides the desired audio resolution
  *
  * Creates sound card, pcm device, sets pcm ops and registers sound card.
  *
@@ -699,7 +701,7 @@  static int audio_tx_completion(struct mo
 	return 0;
 }
 
-/**
+/*
  * Initialization of the struct most_component
  */
 static struct most_component comp = {