Skip to contentSkip to conversation

ALSA: hda - add missing documentation to hdac_i915

PATCH In review Kai Vehmanen 2 participants 4 messages Sep 24, 2020 Sound

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 ALSA: hda - add missing documentation to hdac_i915

Document missing function arguments and fix make W=1 warning:

sound/hda/hdac_i915.c:80: warning: Function parameter or member 'i915' not described in 'connectivity_check' sound/hda/hdac_i915.c:80: warning: Function parameter or member 'hdac' not described in 'connectivity_check'

Fixes 7b882fe3e3e8 ('ALSA: hda - handle multiple i915 device instances')
---
 sound/hda/hdac_i915.c | 2 ++
 1 file changed, 2 insertions(+)
sound/hda/hdac_i915.c +2 -0
index d236e497435d..9592d0c0c254 100644
@@ -75,6 +75,8 @@ EXPORT_SYMBOL_GPL(snd_hdac_i915_set_bclk);
 
 /**
  * Returns true if the devices can be connected for audio.
+ * @i915: i915 PCI device
+ * @hdac: HDA audio controller PCI device
  */
 static bool connectivity_check(struct pci_dev *i915, struct pci_dev *hdac)
 {
Signature · 1 line
2.27.0
#1 lore raw
Quoted 9 lines · Kai Vehmanen

Document missing function arguments and fix make W=1 warning:

sound/hda/hdac_i915.c:80: warning: Function parameter or member 'i915' not described in 'connectivity_check' sound/hda/hdac_i915.c:80: warning: Function parameter or member 'hdac' not described in 'connectivity_check'

Fixes 7b882fe3e3e8 ('ALSA: hda - handle multiple i915 device instances')

Do we really need to put this internal function in the API documents? If not, the right fix would be to drop the kerneldoc marker instead.

thanks,

Takashi

Quoted 20 lines
---
 sound/hda/hdac_i915.c | 2 ++
 1 file changed, 2 insertions(+)
sound/hda/hdac_i915.c +2 -0
index d236e497435d..9592d0c0c254 100644
@@ -75,6 +75,8 @@ EXPORT_SYMBOL_GPL(snd_hdac_i915_set_bclk);
 
 /**
  * Returns true if the devices can be connected for audio.
+ * @i915: i915 PCI device
+ * @hdac: HDA audio controller PCI device
  */
 static bool connectivity_check(struct pci_dev *i915, struct pci_dev *hdac)
 {
Signature · 1 line
2.27.0
#2 lore raw

Hey,

Quoted 6 lines · Takashi Iwai
Quoted 2 lines · Kai Vehmanen

Document missing function arguments and fix make W=1 warning:

Do we really need to put this internal function in the API documents? If not, the right fix would be to drop the kerneldoc marker instead.

I was puzzled at this as well. I took a look at some static internal functions and there were both with (e.g. snd_hdac_make_cmd()) and without kerneldoc markers. But, but, granted, this is without any name prefix, so maybe better to drop the kerneldoc. Let me send a v2.

Br, Kai

#3 lore raw
Quoted 9 lines · Kai Vehmanen

Hey,

Quoted 4 lines · Takashi Iwai
Quoted 2 lines · Kai Vehmanen

Document missing function arguments and fix make W=1 warning:

Quoted 6 lines
Quoted 2 lines

Do we really need to put this internal function in the API documents? If not, the right fix would be to drop the kerneldoc marker instead.

I was puzzled at this as well. I took a look at some static internal functions and there were both with (e.g. snd_hdac_make_cmd()) and without kerneldoc markers.

Some might have been exported functions in the past.

Quoted 2 lines

But, but, granted, this is without any name prefix, so maybe better to drop the kerneldoc. Let me send a v2.

OK, thanks.

Takashi