| Message ID | 1362146456-21077-1-git-send-email-nm@ti.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Fri, Mar 1, 2013 at 9:00 AM, Nishanth Menon <nm@ti.com> wrote: > 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 <airlied@linux.ie> > Cc: Dave Airlie <airlied@redhat.com> > Cc: Adam Jackson <ajax@redhat.com> > Cc: Rodrigo Vivi <rodrigo.vivi@intel.com> > Cc: Ville Syrjälä <ville.syrjala@linux.intel.com> > Cc: dri-devel@lists.freedesktop.org > > Signed-off-by: Nishanth Menon <nm@ti.com> Thanks Nishanth, Reviewed-by: Rob Clark <robdclark@gmail.com> > --- > > V2: review comments incorporated > > V1: http://marc.info/?t=136214115900005&r=1&w=2 > > It does seem the drm_edid.c could do with more 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(-) > > diff --git a/drivers/gpu/drm/drm_edid.c b/drivers/gpu/drm/drm_edid.c > index c194f4e..bd864b5 100644 > --- a/drivers/gpu/drm/drm_edid.c > +++ b/drivers/gpu/drm/drm_edid.c > @@ -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 adapter > + * @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 adapter > * > - * \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: attached connector > + * @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: attached connector > * @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: attached connector > * @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 data > */ > 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: EDID data > * > * 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 > -- > 1.7.9.5 > > _______________________________________________ > dri-devel mailing list > dri-devel@lists.freedesktop.org > http://lists.freedesktop.org/mailman/listinfo/dri-devel
Am Freitag, den 01.03.2013, 08:00 -0600 schrieb Nishanth Menon: > Some basic cleanups for kernel-doc errors or missing documentation > parameters. Nishanth, thanks for doing that! > 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 <airlied@linux.ie> > Cc: Dave Airlie <airlied@redhat.com> > Cc: Adam Jackson <ajax@redhat.com> > Cc: Rodrigo Vivi <rodrigo.vivi@intel.com> > Cc: Ville Syrjälä <ville.syrjala@linux.intel.com> > Cc: dri-devel@lists.freedesktop.org > > Signed-off-by: Nishanth Menon <nm@ti.com> > --- > > V2: review comments incorporated > > V1: http://marc.info/?t=136214115900005&r=1&w=2 > > It does seem the drm_edid.c could do with more 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(-) > > diff --git a/drivers/gpu/drm/drm_edid.c b/drivers/gpu/drm/drm_edid.c > index c194f4e..bd864b5 100644 > --- a/drivers/gpu/drm/drm_edid.c > +++ b/drivers/gpu/drm/drm_edid.c > @@ -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. Some already existing entries do not use »()« behind the function name in the comment. Not sure what the correct way is though. […] Thanks, Paul
On 18:09-20130302, Paul Menzel wrote: > Am Freitag, den 01.03.2013, 08:00 -0600 schrieb Nishanth Menon: > > Some basic cleanups for kernel-doc errors or missing documentation > > parameters. > > Nishanth, thanks for doing that! glad to be of help. > > > index c194f4e..bd864b5 100644 > > --- a/drivers/gpu/drm/drm_edid.c > > +++ b/drivers/gpu/drm/drm_edid.c > > @@ -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. > > Some already existing entries do not use »()« behind the function name > in the comment. Not sure what the correct way is though. I followed the format as in: http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/kernel-doc-nano-HOWTO.txt#n55 That said, I might suggest someone more knowledgable than I look through the drm_edid.c - there seems to be code alignment issues etc which I did not fix up. running Lindent quickly shows: http://pastebin.com/vaYFQDHv
On 10:27-20130304, Nishanth Menon wrote: > On 18:09-20130302, Paul Menzel wrote: > > Am Freitag, den 01.03.2013, 08:00 -0600 schrieb Nishanth Menon: > > > Some basic cleanups for kernel-doc errors or missing documentation > > > parameters. [..] > > > index c194f4e..bd864b5 100644 > > > --- a/drivers/gpu/drm/drm_edid.c > > > +++ b/drivers/gpu/drm/drm_edid.c > > > @@ -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. > > > > Some already existing entries do not use »()« behind the function name > > in the comment. Not sure what the correct way is though. > I followed the format as in: > http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/kernel-doc-nano-HOWTO.txt#n55 just a ping to confirm if there are any further changes required?
diff --git a/drivers/gpu/drm/drm_edid.c b/drivers/gpu/drm/drm_edid.c index c194f4e..bd864b5 100644 --- a/drivers/gpu/drm/drm_edid.c +++ b/drivers/gpu/drm/drm_edid.c @@ -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 adapter + * @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 adapter * - * \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: attached connector + * @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: attached connector * @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: attached connector * @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 data */ 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: EDID data * * 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