Skip to contentSkip to conversation

drm/edid: kernel-doc minimal cleanup

PATCH Superseded Nishanth Menon 2 participants 4 messages Feb 28, 2013 – Mar 1, 2013

Subsystems (2)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 drm/edid: kernel-doc minimal cleanup

Some basic cleanups for kernel-doc errors or missing documentation parameters.

Warnings generated by ./scripts/kernel-doc drivers/gpu/drm/drm_edid.c >Kerr

Warning(drivers/gpu/drm/drm_edid.c:997): No description found for parameter 'adapter' Warning(drivers/gpu/drm/drm_edid.c:997): No description found for parameter 'buf' Warning(drivers/gpu/drm/drm_edid.c:997): No description found for parameter 'block' Warning(drivers/gpu/drm/drm_edid.c:997): No description found for parameter 'len' Warning(drivers/gpu/drm/drm_edid.c:1138): No description found for parameter 'adapter' Warning(drivers/gpu/drm/drm_edid.c:1467): No description found for parameter 'connector' Warning(drivers/gpu/drm/drm_edid.c:1467): No description found for parameter 'edid' Warning(drivers/gpu/drm/drm_edid.c:1467): No description found for parameter 'revision' Warning(drivers/gpu/drm/drm_edid.c:1467): Excess function parameter 'timing_level' description in 'drm_mode_std' Warning(drivers/gpu/drm/drm_edid.c:2010): No description found for parameter 'connector' Warning(drivers/gpu/drm/drm_edid.c:2072): No description found for parameter 'connector' Warning(drivers/gpu/drm/drm_edid.c:2237): No description found for parameter 'edid' Warning(drivers/gpu/drm/drm_edid.c:2616): No description found for parameter 'edid' Warning(drivers/gpu/drm/drm_edid.c:2658): No description found for parameter 'edid'

Cc David Airlie <[email protected]>
Cc Dave Airlie <[email protected]>
Cc Adam Jackson <[email protected]>
Cc Rodrigo Vivi <[email protected]>

---
It does seem the drm_edid.c could do with some amount of documentation cleanup,
but I have stayed with the bare minimum.
the above error is based off:
master de1a226 Merge tag 'writeback-fixes' of git://git.kernel.org/pub/scm/linux/kernel/git/wfg/linux
from: git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git

defconfig used: omap2plus_defconfig

Disclaimer: I am no drm expert, and I tried to use my best judgement about what the meaning of the parameters might be, hope it helps.

 drivers/gpu/drm/drm_edid.c |   31 +++++++++++++++++++------------
 1 file changed, 19 insertions(+), 12 deletions(-)
drivers/gpu/drm/drm_edid.c +19 -12
index c194f4e..f604c5f 100644
@@ -982,14 +982,14 @@ EXPORT_SYMBOL(drm_edid_is_valid);
 
 #define DDC_SEGMENT_ADDR 0x30
 /**
- * Get EDID information via I2C.
- *
- * \param adapter : i2c device adaptor
- * \param buf     : EDID data buffer to be filled
- * \param len     : EDID data buffer length
- * \return 0 on success or -1 on failure.
+ * drm_do_probe_ddc_edid() - Get EDID information via I2C.
+ * @adapter:	i2c device adaptor
+ * @buf:	EDID data buffer to be filled
+ * @block:	EDID block to get
+ * @len:	EDID data buffer length
  *
  * Try to fetch EDID information by calling i2c driver function.
+ * Return 0 on success or -1 on failure.
  */
 static int
 drm_do_probe_ddc_edid(struct i2c_adapter *adapter, unsigned char *buf,
@@ -1128,10 +1128,10 @@ out:
 }
 
 /**
- * Probe DDC presence.
+ * drm_probe_ddc() - Probe DDC presence
+ * @adapter:	i2c device adaptor
  *
- * \param adapter : i2c device adaptor
- * \return 1 on success
+ * returns 1 on success
  */
 bool
 drm_probe_ddc(struct i2c_adapter *adapter)
@@ -1455,8 +1455,10 @@ bad_std_timing(u8 a, u8 b)
 
 /**
  * drm_mode_std - convert standard mode info (width, height, refresh) into mode
+ * @connector: connector corresponding to the HDMI/DP sink
+ * @edid: EDID data
  * @t: standard timing params
- * @timing_level: standard timing level
+ * @revision: EDID revision
  *
  * Take the standard timing params (in this case width, aspect, and refresh)
  * and convert them into a real mode using CVT/GTF/DMT.
@@ -2000,6 +2002,7 @@ do_established_modes(struct detailed_timing *timing, void *c)
 
 /**
  * add_established_modes - get est. modes from EDID and add them
+ * @connector: connector corresponding to the HDMI/DP sink
  * @edid: EDID block to scan
  *
  * Each EDID block contains a bitmap of the supported "established modes" list
@@ -2062,6 +2065,7 @@ do_standard_modes(struct detailed_timing *timing, void *c)
 
 /**
  * add_standard_modes - get std. modes from EDID and add them
+ * @connector: connector corresponding to the HDMI/DP sink
  * @edid: EDID block to scan
  *
  * Standard modes can be calculated using the appropriate standard (DMT,
@@ -2192,7 +2196,7 @@ do_detailed_mode(struct detailed_timing *timing, void *c)
 	}
 }
 
-/*
+/**
  * add_detailed_modes - Add modes from detailed timings
  * @connector: attached connector
  * @edid: EDID block to scan
@@ -2231,7 +2235,8 @@ add_detailed_modes(struct drm_connector *connector, struct edid *edid,
 #define EDID_CEA_VCDB_QS	(1 << 6)
 
 /**
- * Search EDID for CEA extension block.
+ * drm_find_cea_extension() - Search EDID for CEA extension block.
+ * @edid:	EDID block to scan
  */
 u8 *drm_find_cea_extension(struct edid *edid)
 {
@@ -2604,6 +2609,7 @@ EXPORT_SYMBOL(drm_detect_hdmi_monitor);
 
 /**
  * drm_detect_monitor_audio - check monitor audio capability
+ * @edid: monitor EDID information
  *
  * Monitor should have CEA extension block.
  * If monitor has 'basic audio', but no CEA audio blocks, it's 'basic
@@ -2649,6 +2655,7 @@ EXPORT_SYMBOL(drm_detect_monitor_audio);
 
 /**
  * drm_rgb_quant_range_selectable - is RGB quantization range selectable?
+ * @edid: EDID data
  *
  * Check whether the monitor reports the RGB quantization range selection
  * as supported. The AVI infoframe can then be used to inform the monitor
Signature · 1 line
1.7.9.5
#1 lore raw
Quoted 48 lines · Nishanth Menon

Some basic cleanups for kernel-doc errors or missing documentation parameters.

Warnings generated by ./scripts/kernel-doc drivers/gpu/drm/drm_edid.c >Kerr

Warning(drivers/gpu/drm/drm_edid.c:997): No description found for parameter 'adapter' Warning(drivers/gpu/drm/drm_edid.c:997): No description found for parameter 'buf' Warning(drivers/gpu/drm/drm_edid.c:997): No description found for parameter 'block' Warning(drivers/gpu/drm/drm_edid.c:997): No description found for parameter 'len' Warning(drivers/gpu/drm/drm_edid.c:1138): No description found for parameter 'adapter' Warning(drivers/gpu/drm/drm_edid.c:1467): No description found for parameter 'connector' Warning(drivers/gpu/drm/drm_edid.c:1467): No description found for parameter 'edid' Warning(drivers/gpu/drm/drm_edid.c:1467): No description found for parameter 'revision' Warning(drivers/gpu/drm/drm_edid.c:1467): Excess function parameter 'timing_level' description in 'drm_mode_std' Warning(drivers/gpu/drm/drm_edid.c:2010): No description found for parameter 'connector' Warning(drivers/gpu/drm/drm_edid.c:2072): No description found for parameter 'connector' Warning(drivers/gpu/drm/drm_edid.c:2237): No description found for parameter 'edid' Warning(drivers/gpu/drm/drm_edid.c:2616): No description found for parameter 'edid' Warning(drivers/gpu/drm/drm_edid.c:2658): No description found for parameter 'edid'

Cc David Airlie <[email protected]>
Cc Dave Airlie <[email protected]>
Cc Adam Jackson <[email protected]>
Cc Rodrigo Vivi <[email protected]>

---
It does seem the drm_edid.c could do with some amount of documentation cleanup,
but I have stayed with the bare minimum.
the above error is based off:
master de1a226 Merge tag 'writeback-fixes' of git://git.kernel.org/pub/scm/linux/kernel/git/wfg/linux
from: git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git

defconfig used: omap2plus_defconfig

Disclaimer: I am no drm expert, and I tried to use my best judgement about what the meaning of the parameters might be, hope it helps.

 drivers/gpu/drm/drm_edid.c |   31 +++++++++++++++++++------------
 1 file changed, 19 insertions(+), 12 deletions(-)
drivers/gpu/drm/drm_edid.c +0 -0
index c194f4e..f604c5f 100644
@@ -982,14 +982,14 @@ EXPORT_SYMBOL(drm_edid_is_valid);
 

drivers/gpu/drm/drm_edid.c EXPORT_SYMBOL(drm_edid_is_valid); · line 986

Quoted 10 lines
drivers/gpu/drm/drm_edid.c +2 -6
 #define DDC_SEGMENT_ADDR 0x30
 /**
- * Get EDID information via I2C.
- *
- * \param adapter : i2c device adaptor
- * \param buf     : EDID data buffer to be filled
- * \param len     : EDID data buffer length
- * \return 0 on success or -1 on failure.
+ * drm_do_probe_ddc_edid() - Get EDID information via I2C.
+ * @adapter:	i2c device adaptor

nit: adapter vs. adaptor

Quoted 24 lines
drivers/gpu/drm/drm_edid.c +7 -3
+ * @buf:	EDID data buffer to be filled
+ * @block:	EDID block to get
+ * @len:	EDID data buffer length
  *
  * Try to fetch EDID information by calling i2c driver function.
+ * Return 0 on success or -1 on failure.
  */
 static int
 drm_do_probe_ddc_edid(struct i2c_adapter *adapter, unsigned char *buf,
@@ -1128,10 +1128,10 @@ out:
 }
 
 /**
- * Probe DDC presence.
+ * drm_probe_ddc() - Probe DDC presence
+ * @adapter:	i2c device adaptor
  *
- * \param adapter : i2c device adaptor
- * \return 1 on success
+ * returns 1 on success
  */
 bool
 drm_probe_ddc(struct i2c_adapter *adapter)

drivers/gpu/drm/drm_edid.c bad_std_timing(u8 a, u8 b) · line 1458

Quoted 4 lines
drivers/gpu/drm/drm_edid.c +1 -0
@@ -1455,8 +1455,10 @@ bad_std_timing(u8 a, u8 b)
 
 /**
  * drm_mode_std - convert standard mode info (width, height, refresh) into mode
+ * @connector: connector corresponding to the HDMI/DP sink

EDID isn't limited to HDMI/DP.

Quoted 51 lines
drivers/gpu/drm/drm_edid.c +8 -3
+ * @edid: EDID data
  * @t: standard timing params
- * @timing_level: standard timing level
+ * @revision: EDID revision
  *
  * Take the standard timing params (in this case width, aspect, and refresh)
  * and convert them into a real mode using CVT/GTF/DMT.
@@ -2000,6 +2002,7 @@ do_established_modes(struct detailed_timing *timing, void *c)
 
 /**
  * add_established_modes - get est. modes from EDID and add them
+ * @connector: connector corresponding to the HDMI/DP sink
  * @edid: EDID block to scan
  *
  * Each EDID block contains a bitmap of the supported "established modes" list
@@ -2062,6 +2065,7 @@ do_standard_modes(struct detailed_timing *timing, void *c)
 
 /**
  * add_standard_modes - get std. modes from EDID and add them
+ * @connector: connector corresponding to the HDMI/DP sink
  * @edid: EDID block to scan
  *
  * Standard modes can be calculated using the appropriate standard (DMT,
@@ -2192,7 +2196,7 @@ do_detailed_mode(struct detailed_timing *timing, void *c)
 	}
 }
 
-/*
+/**
  * add_detailed_modes - Add modes from detailed timings
  * @connector: attached connector
  * @edid: EDID block to scan
@@ -2231,7 +2235,8 @@ add_detailed_modes(struct drm_connector *connector, struct edid *edid,
 #define EDID_CEA_VCDB_QS	(1 << 6)
 
 /**
- * Search EDID for CEA extension block.
+ * drm_find_cea_extension() - Search EDID for CEA extension block.
+ * @edid:	EDID block to scan
  */
 u8 *drm_find_cea_extension(struct edid *edid)
 {
@@ -2604,6 +2609,7 @@ EXPORT_SYMBOL(drm_detect_hdmi_monitor);
 
 /**
  * drm_detect_monitor_audio - check monitor audio capability
+ * @edid: monitor EDID information
  *
  * Monitor should have CEA extension block.
  * If monitor has 'basic audio', but no CEA audio blocks, it's 'basic

drivers/gpu/drm/drm_edid.c EXPORT_SYMBOL(drm_detect_monitor_audio); · line 2658

Quoted 4 lines
drivers/gpu/drm/drm_edid.c +1 -0
@@ -2649,6 +2655,7 @@ EXPORT_SYMBOL(drm_detect_monitor_audio);
 
 /**
  * drm_rgb_quant_range_selectable - is RGB quantization range selectable?
+ * @edid: EDID data

nit: Different description for the same thing between this and the previous hunk.

Quoted 10 lines
drivers/gpu/drm/drm_edid.c +0 -0
  *
  * Check whether the monitor reports the RGB quantization range selection
  * as supported. The AVI infoframe can then be used to inform the monitor
Signature · 6 lines
1.7.9.5

_______________________________________________
dri-devel mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/dri-devel
Signature · 2 lines
Ville Syrjälä
Intel OTC
#2 lore raw
Quoted 1 line · Ville Syrjälä

On Thu, Feb 28, 2013 at 05:13:09PM -0600, Nishanth Menon wrote:

[..]

Quoted 14 lines

drivers/gpu/drm/drm_edid.c EXPORT_SYMBOL(drm_edid_is_valid); · line 986

Quoted 12 lines
drivers/gpu/drm/drm_edid.c +2 -6
@@ -982,14 +982,14 @@ EXPORT_SYMBOL(drm_edid_is_valid);
 
 #define DDC_SEGMENT_ADDR 0x30
 /**
- * Get EDID information via I2C.
- *
- * \param adapter : i2c device adaptor
- * \param buf     : EDID data buffer to be filled
- * \param len     : EDID data buffer length
- * \return 0 on success or -1 on failure.
+ * drm_do_probe_ddc_edid() - Get EDID information via I2C.
+ * @adapter:	i2c device adaptor

nit: adapter vs. adaptor

Thanks for catching it.

Quoted 32 lines
Quoted 25 lines
drivers/gpu/drm/drm_edid.c +7 -3
+ * @buf:	EDID data buffer to be filled
+ * @block:	EDID block to get
+ * @len:	EDID data buffer length
  *
  * Try to fetch EDID information by calling i2c driver function.
+ * Return 0 on success or -1 on failure.
  */
 static int
 drm_do_probe_ddc_edid(struct i2c_adapter *adapter, unsigned char *buf,
@@ -1128,10 +1128,10 @@ out:
 }
 
 /**
- * Probe DDC presence.
+ * drm_probe_ddc() - Probe DDC presence
+ * @adapter:	i2c device adaptor
  *
- * \param adapter : i2c device adaptor
- * \return 1 on success
+ * returns 1 on success
  */
 bool
 drm_probe_ddc(struct i2c_adapter *adapter)

drivers/gpu/drm/drm_edid.c bad_std_timing(u8 a, u8 b) · line 1458

Quoted 4 lines
drivers/gpu/drm/drm_edid.c +1 -0
@@ -1455,8 +1455,10 @@ bad_std_timing(u8 a, u8 b)
 
 /**
  * drm_mode_std - convert standard mode info (width, height, refresh) into mode
+ * @connector: connector corresponding to the HDMI/DP sink

EDID isn't limited to HDMI/DP.

[..]

Quoted 7 lines
Quoted 4 lines

/**
* drm_rgb_quant_range_selectable - is RGB quantization range selectable?
+ * @edid: EDID data

nit: Different description for the same thing between this and the previous hunk.

agreed. How about just EDID data?

Signature · 2 lines
Regards,
Nishanth Menon
#3 lore raw
Quoted 52 lines · Nishanth Menon
Quoted 1 line · Ville Syrjälä

On Thu, Feb 28, 2013 at 05:13:09PM -0600, Nishanth Menon wrote:

[..]

Quoted 14 lines

drivers/gpu/drm/drm_edid.c EXPORT_SYMBOL(drm_edid_is_valid); · line 986

Quoted 12 lines
drivers/gpu/drm/drm_edid.c +2 -6
@@ -982,14 +982,14 @@ EXPORT_SYMBOL(drm_edid_is_valid);
 
 #define DDC_SEGMENT_ADDR 0x30
 /**
- * Get EDID information via I2C.
- *
- * \param adapter : i2c device adaptor
- * \param buf     : EDID data buffer to be filled
- * \param len     : EDID data buffer length
- * \return 0 on success or -1 on failure.
+ * drm_do_probe_ddc_edid() - Get EDID information via I2C.
+ * @adapter:	i2c device adaptor

nit: adapter vs. adaptor

Thanks for catching it.

Quoted 32 lines
Quoted 25 lines
drivers/gpu/drm/drm_edid.c +7 -3
+ * @buf:	EDID data buffer to be filled
+ * @block:	EDID block to get
+ * @len:	EDID data buffer length
  *
  * Try to fetch EDID information by calling i2c driver function.
+ * Return 0 on success or -1 on failure.
  */
 static int
 drm_do_probe_ddc_edid(struct i2c_adapter *adapter, unsigned char *buf,
@@ -1128,10 +1128,10 @@ out:
 }
 
 /**
- * Probe DDC presence.
+ * drm_probe_ddc() - Probe DDC presence
+ * @adapter:	i2c device adaptor
  *
- * \param adapter : i2c device adaptor
- * \return 1 on success
+ * returns 1 on success
  */
 bool
 drm_probe_ddc(struct i2c_adapter *adapter)

drivers/gpu/drm/drm_edid.c bad_std_timing(u8 a, u8 b) · line 1458

Quoted 4 lines
drivers/gpu/drm/drm_edid.c +1 -0
@@ -1455,8 +1455,10 @@ bad_std_timing(u8 a, u8 b)
 
 /**
  * drm_mode_std - convert standard mode info (width, height, refresh) into mode
+ * @connector: connector corresponding to the HDMI/DP sink

EDID isn't limited to HDMI/DP.

[..]

Quoted 1 line
Quoted 1 line
Quoted 7 lines
Quoted 6 lines
Quoted 3 lines

/**
* drm_rgb_quant_range_selectable - is RGB quantization range selectable?
+ * @edid: EDID data

nit: Different description for the same thing between this and the previous hunk.

agreed. How about just EDID data?

Fine by me.

Signature · 2 lines
Ville Syrjälä
Intel OTC