| Message ID | 20240516002642.6659-1-rdunlap@infradead.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | drm/display/dp: fix all kernel-doc warnings | expand |
On Wed, May 15, 2024 at 05:26:42PM -0700, Randy Dunlap wrote: > Fix a struct member name in &struct drm_dp_as_sdp. > Add Returns: kernel-doc syntax for 4 functions. > In the Returns: sections, spell "%true" and "%false" consistently. > > Fixes these kernel-doc warnings: > > drm_dp_helper.h:126: warning: Function parameter or struct member 'mode' not described in 'drm_dp_as_sdp' > drm_dp_helper.h:126: warning: Excess struct member 'operation_mode' description in 'drm_dp_as_sdp' > drm_dp_helper.h:237: warning: No description found for return value of 'drm_dp_dsc_sink_supports_format' > drm_dp_helper.h:539: warning: No description found for return value of 'drm_dp_dpcd_readb' > drm_dp_helper.h:554: warning: No description found for return value of 'drm_dp_dpcd_writeb' > drm_dp_helper.h:721: warning: No description found for return value of 'drm_dp_has_quirk' > > Signed-off-by: Randy Dunlap <rdunlap@infradead.org> > --- > Cc: David Airlie <airlied@gmail.com> > Cc: Daniel Vetter <daniel@ffwll.ch> > Cc: dri-devel@lists.freedesktop.org > Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com> > Cc: Maxime Ripard <mripard@kernel.org> > Cc: Thomas Zimmermann <tzimmermann@suse.de> > > include/drm/display/drm_dp_helper.h | 17 +++++++++-------- > 1 file changed, 9 insertions(+), 8 deletions(-) > > diff -- a/include/drm/display/drm_dp_helper.h b/include/drm/display/drm_dp_helper.h > --- a/include/drm/display/drm_dp_helper.h > +++ b/include/drm/display/drm_dp_helper.h > @@ -112,7 +112,7 @@ struct drm_dp_vsc_sdp { > * @target_rr: Target Refresh > * @duration_incr_ms: Successive frame duration increase > * @duration_decr_ms: Successive frame duration decrease > - * @operation_mode: Adaptive Sync Operation Mode > + * @mode: Adaptive Sync Operation Mode > */ > struct drm_dp_as_sdp { > unsigned char sdp_type; > @@ -230,7 +230,8 @@ drm_dp_dsc_sink_max_slice_width(const u8 > * @dsc_dpcd : DSC-capability DPCDs of the sink > * @output_format: output_format which is to be checked > * > - * Returns true if the sink supports DSC with the given output_format, false otherwise. > + * Returns: %true if the sink supports DSC with the given output_format, > + * %false otherwise. > */ > static inline bool > drm_dp_dsc_sink_supports_format(const u8 dsc_dpcd[DP_DSC_RECEIVER_CAP_SIZE], u8 output_format) > @@ -280,8 +281,8 @@ drm_dp_sink_can_do_video_without_timing_ > * backlight features but which require the brightness be set through PWM, and don't support setting > * the brightness level via the DPCD. > * > - * Returns: %True if @edp_dpcd indicates that VESA backlight controls are supported, %false > - * otherwise > + * Returns: %true if @edp_dpcd indicates that VESA backlight controls are > + * supported, %false otherwise If you are touching this part, maybe it's better to change 'Returns' to 'Return' as documented by Documentation/doc-guide/kernel-doc.rst ? (the same comment applies to other chunks in the patch, I've trimmed them). > */ > static inline bool > drm_edp_backlight_supported(const u8 edp_dpcd[EDP_DISPLAY_CTL_CAP_SIZE])
Hi Dmitry, On 5/20/24 3:37 AM, Dmitry Baryshkov wrote: > On Wed, May 15, 2024 at 05:26:42PM -0700, Randy Dunlap wrote: >> Fix a struct member name in &struct drm_dp_as_sdp. >> Add Returns: kernel-doc syntax for 4 functions. >> In the Returns: sections, spell "%true" and "%false" consistently. >> >> Fixes these kernel-doc warnings: >> >> drm_dp_helper.h:126: warning: Function parameter or struct member 'mode' not described in 'drm_dp_as_sdp' >> drm_dp_helper.h:126: warning: Excess struct member 'operation_mode' description in 'drm_dp_as_sdp' >> drm_dp_helper.h:237: warning: No description found for return value of 'drm_dp_dsc_sink_supports_format' >> drm_dp_helper.h:539: warning: No description found for return value of 'drm_dp_dpcd_readb' >> drm_dp_helper.h:554: warning: No description found for return value of 'drm_dp_dpcd_writeb' >> drm_dp_helper.h:721: warning: No description found for return value of 'drm_dp_has_quirk' >> >> Signed-off-by: Randy Dunlap <rdunlap@infradead.org> >> --- >> Cc: David Airlie <airlied@gmail.com> >> Cc: Daniel Vetter <daniel@ffwll.ch> >> Cc: dri-devel@lists.freedesktop.org >> Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com> >> Cc: Maxime Ripard <mripard@kernel.org> >> Cc: Thomas Zimmermann <tzimmermann@suse.de> >> >> include/drm/display/drm_dp_helper.h | 17 +++++++++-------- >> 1 file changed, 9 insertions(+), 8 deletions(-) >> >> diff -- a/include/drm/display/drm_dp_helper.h b/include/drm/display/drm_dp_helper.h >> --- a/include/drm/display/drm_dp_helper.h >> +++ b/include/drm/display/drm_dp_helper.h >> @@ -112,7 +112,7 @@ struct drm_dp_vsc_sdp { >> * @target_rr: Target Refresh >> * @duration_incr_ms: Successive frame duration increase >> * @duration_decr_ms: Successive frame duration decrease >> - * @operation_mode: Adaptive Sync Operation Mode >> + * @mode: Adaptive Sync Operation Mode >> */ >> struct drm_dp_as_sdp { >> unsigned char sdp_type; >> @@ -230,7 +230,8 @@ drm_dp_dsc_sink_max_slice_width(const u8 >> * @dsc_dpcd : DSC-capability DPCDs of the sink >> * @output_format: output_format which is to be checked >> * >> - * Returns true if the sink supports DSC with the given output_format, false otherwise. >> + * Returns: %true if the sink supports DSC with the given output_format, >> + * %false otherwise. >> */ >> static inline bool >> drm_dp_dsc_sink_supports_format(const u8 dsc_dpcd[DP_DSC_RECEIVER_CAP_SIZE], u8 output_format) >> @@ -280,8 +281,8 @@ drm_dp_sink_can_do_video_without_timing_ >> * backlight features but which require the brightness be set through PWM, and don't support setting >> * the brightness level via the DPCD. >> * >> - * Returns: %True if @edp_dpcd indicates that VESA backlight controls are supported, %false >> - * otherwise >> + * Returns: %true if @edp_dpcd indicates that VESA backlight controls are >> + * supported, %false otherwise > > If you are touching this part, maybe it's better to change 'Returns' to > 'Return' as documented by Documentation/doc-guide/kernel-doc.rst ? > (the same comment applies to other chunks in the patch, I've trimmed > them). scripts/kernel-doc accepts either spelling, but sure, I can change these. Thanks. >> */ >> static inline bool >> drm_edp_backlight_supported(const u8 edp_dpcd[EDP_DISPLAY_CTL_CAP_SIZE]) >
On Tue, May 21, 2024 at 08:59:06PM -0700, Randy Dunlap wrote: > Hi Dmitry, > > On 5/20/24 3:37 AM, Dmitry Baryshkov wrote: > > On Wed, May 15, 2024 at 05:26:42PM -0700, Randy Dunlap wrote: > >> Fix a struct member name in &struct drm_dp_as_sdp. > >> Add Returns: kernel-doc syntax for 4 functions. > >> In the Returns: sections, spell "%true" and "%false" consistently. > >> > >> Fixes these kernel-doc warnings: > >> > >> drm_dp_helper.h:126: warning: Function parameter or struct member 'mode' not described in 'drm_dp_as_sdp' > >> drm_dp_helper.h:126: warning: Excess struct member 'operation_mode' description in 'drm_dp_as_sdp' > >> drm_dp_helper.h:237: warning: No description found for return value of 'drm_dp_dsc_sink_supports_format' > >> drm_dp_helper.h:539: warning: No description found for return value of 'drm_dp_dpcd_readb' > >> drm_dp_helper.h:554: warning: No description found for return value of 'drm_dp_dpcd_writeb' > >> drm_dp_helper.h:721: warning: No description found for return value of 'drm_dp_has_quirk' > >> > >> Signed-off-by: Randy Dunlap <rdunlap@infradead.org> > >> --- > >> Cc: David Airlie <airlied@gmail.com> > >> Cc: Daniel Vetter <daniel@ffwll.ch> > >> Cc: dri-devel@lists.freedesktop.org > >> Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com> > >> Cc: Maxime Ripard <mripard@kernel.org> > >> Cc: Thomas Zimmermann <tzimmermann@suse.de> > >> > >> include/drm/display/drm_dp_helper.h | 17 +++++++++-------- > >> 1 file changed, 9 insertions(+), 8 deletions(-) > >> > >> diff -- a/include/drm/display/drm_dp_helper.h b/include/drm/display/drm_dp_helper.h > >> --- a/include/drm/display/drm_dp_helper.h > >> +++ b/include/drm/display/drm_dp_helper.h > >> @@ -112,7 +112,7 @@ struct drm_dp_vsc_sdp { > >> * @target_rr: Target Refresh > >> * @duration_incr_ms: Successive frame duration increase > >> * @duration_decr_ms: Successive frame duration decrease > >> - * @operation_mode: Adaptive Sync Operation Mode > >> + * @mode: Adaptive Sync Operation Mode > >> */ > >> struct drm_dp_as_sdp { > >> unsigned char sdp_type; > >> @@ -230,7 +230,8 @@ drm_dp_dsc_sink_max_slice_width(const u8 > >> * @dsc_dpcd : DSC-capability DPCDs of the sink > >> * @output_format: output_format which is to be checked > >> * > >> - * Returns true if the sink supports DSC with the given output_format, false otherwise. > >> + * Returns: %true if the sink supports DSC with the given output_format, > >> + * %false otherwise. > >> */ > >> static inline bool > >> drm_dp_dsc_sink_supports_format(const u8 dsc_dpcd[DP_DSC_RECEIVER_CAP_SIZE], u8 output_format) > >> @@ -280,8 +281,8 @@ drm_dp_sink_can_do_video_without_timing_ > >> * backlight features but which require the brightness be set through PWM, and don't support setting > >> * the brightness level via the DPCD. > >> * > >> - * Returns: %True if @edp_dpcd indicates that VESA backlight controls are supported, %false > >> - * otherwise > >> + * Returns: %true if @edp_dpcd indicates that VESA backlight controls are > >> + * supported, %false otherwise > > > > If you are touching this part, maybe it's better to change 'Returns' to > > 'Return' as documented by Documentation/doc-guide/kernel-doc.rst ? > > (the same comment applies to other chunks in the patch, I've trimmed > > them). > > scripts/kernel-doc accepts either spelling, but sure, I can change these. > Thanks. An alternative way would be to fix kernel-doc.rst :-) > > >> */ > >> static inline bool > >> drm_edp_backlight_supported(const u8 edp_dpcd[EDP_DISPLAY_CTL_CAP_SIZE]) > > > > -- > #Randy > https://people.kernel.org/tglx/notes-about-netiquette > https://subspace.kernel.org/etiquette.html
On 5/22/24 2:37 AM, Dmitry Baryshkov wrote: > On Tue, May 21, 2024 at 08:59:06PM -0700, Randy Dunlap wrote: >> Hi Dmitry, >> >> On 5/20/24 3:37 AM, Dmitry Baryshkov wrote: >>> On Wed, May 15, 2024 at 05:26:42PM -0700, Randy Dunlap wrote: >>>> Fix a struct member name in &struct drm_dp_as_sdp. >>>> Add Returns: kernel-doc syntax for 4 functions. >>>> In the Returns: sections, spell "%true" and "%false" consistently. >>>> >>>> Fixes these kernel-doc warnings: >>>> >>>> drm_dp_helper.h:126: warning: Function parameter or struct member 'mode' not described in 'drm_dp_as_sdp' >>>> drm_dp_helper.h:126: warning: Excess struct member 'operation_mode' description in 'drm_dp_as_sdp' >>>> drm_dp_helper.h:237: warning: No description found for return value of 'drm_dp_dsc_sink_supports_format' >>>> drm_dp_helper.h:539: warning: No description found for return value of 'drm_dp_dpcd_readb' >>>> drm_dp_helper.h:554: warning: No description found for return value of 'drm_dp_dpcd_writeb' >>>> drm_dp_helper.h:721: warning: No description found for return value of 'drm_dp_has_quirk' >>>> >>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org> >>>> --- >>>> Cc: David Airlie <airlied@gmail.com> >>>> Cc: Daniel Vetter <daniel@ffwll.ch> >>>> Cc: dri-devel@lists.freedesktop.org >>>> Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com> >>>> Cc: Maxime Ripard <mripard@kernel.org> >>>> Cc: Thomas Zimmermann <tzimmermann@suse.de> >>>> >>>> include/drm/display/drm_dp_helper.h | 17 +++++++++-------- >>>> 1 file changed, 9 insertions(+), 8 deletions(-) >>>> >>>> diff -- a/include/drm/display/drm_dp_helper.h b/include/drm/display/drm_dp_helper.h >>>> --- a/include/drm/display/drm_dp_helper.h >>>> +++ b/include/drm/display/drm_dp_helper.h >>>> @@ -112,7 +112,7 @@ struct drm_dp_vsc_sdp { >>>> * @target_rr: Target Refresh >>>> * @duration_incr_ms: Successive frame duration increase >>>> * @duration_decr_ms: Successive frame duration decrease >>>> - * @operation_mode: Adaptive Sync Operation Mode >>>> + * @mode: Adaptive Sync Operation Mode >>>> */ >>>> struct drm_dp_as_sdp { >>>> unsigned char sdp_type; >>>> @@ -230,7 +230,8 @@ drm_dp_dsc_sink_max_slice_width(const u8 >>>> * @dsc_dpcd : DSC-capability DPCDs of the sink >>>> * @output_format: output_format which is to be checked >>>> * >>>> - * Returns true if the sink supports DSC with the given output_format, false otherwise. >>>> + * Returns: %true if the sink supports DSC with the given output_format, >>>> + * %false otherwise. >>>> */ >>>> static inline bool >>>> drm_dp_dsc_sink_supports_format(const u8 dsc_dpcd[DP_DSC_RECEIVER_CAP_SIZE], u8 output_format) >>>> @@ -280,8 +281,8 @@ drm_dp_sink_can_do_video_without_timing_ >>>> * backlight features but which require the brightness be set through PWM, and don't support setting >>>> * the brightness level via the DPCD. >>>> * >>>> - * Returns: %True if @edp_dpcd indicates that VESA backlight controls are supported, %false >>>> - * otherwise >>>> + * Returns: %true if @edp_dpcd indicates that VESA backlight controls are >>>> + * supported, %false otherwise >>> >>> If you are touching this part, maybe it's better to change 'Returns' to >>> 'Return' as documented by Documentation/doc-guide/kernel-doc.rst ? >>> (the same comment applies to other chunks in the patch, I've trimmed >>> them). >> >> scripts/kernel-doc accepts either spelling, but sure, I can change these. >> Thanks. > > An alternative way would be to fix kernel-doc.rst :-) Yes, I thought of that last night. I'll submit such a change. Thanks. >> >>>> */ >>>> static inline bool >>>> drm_edp_backlight_supported(const u8 edp_dpcd[EDP_DISPLAY_CTL_CAP_SIZE]) >>> >> >> -- >> #Randy >> https://people.kernel.org/tglx/notes-about-netiquette >> https://subspace.kernel.org/etiquette.html >
diff -- a/include/drm/display/drm_dp_helper.h b/include/drm/display/drm_dp_helper.h --- a/include/drm/display/drm_dp_helper.h +++ b/include/drm/display/drm_dp_helper.h @@ -112,7 +112,7 @@ struct drm_dp_vsc_sdp { * @target_rr: Target Refresh * @duration_incr_ms: Successive frame duration increase * @duration_decr_ms: Successive frame duration decrease - * @operation_mode: Adaptive Sync Operation Mode + * @mode: Adaptive Sync Operation Mode */ struct drm_dp_as_sdp { unsigned char sdp_type; @@ -230,7 +230,8 @@ drm_dp_dsc_sink_max_slice_width(const u8 * @dsc_dpcd : DSC-capability DPCDs of the sink * @output_format: output_format which is to be checked * - * Returns true if the sink supports DSC with the given output_format, false otherwise. + * Returns: %true if the sink supports DSC with the given output_format, + * %false otherwise. */ static inline bool drm_dp_dsc_sink_supports_format(const u8 dsc_dpcd[DP_DSC_RECEIVER_CAP_SIZE], u8 output_format) @@ -280,8 +281,8 @@ drm_dp_sink_can_do_video_without_timing_ * backlight features but which require the brightness be set through PWM, and don't support setting * the brightness level via the DPCD. * - * Returns: %True if @edp_dpcd indicates that VESA backlight controls are supported, %false - * otherwise + * Returns: %true if @edp_dpcd indicates that VESA backlight controls are + * supported, %false otherwise */ static inline bool drm_edp_backlight_supported(const u8 edp_dpcd[EDP_DISPLAY_CTL_CAP_SIZE]) @@ -295,7 +296,7 @@ drm_edp_backlight_supported(const u8 edp * * Determine if the provided link rate is an UHBR rate. * - * Returns: %True if @link_rate is an UHBR rate. + * Returns: %true if @link_rate is an UHBR rate. */ static inline bool drm_dp_is_uhbr_rate(int link_rate) { @@ -531,7 +532,7 @@ ssize_t drm_dp_dpcd_write(struct drm_dp_ * @offset: address of the register to read * @valuep: location where the value of the register will be stored * - * Returns the number of bytes transferred (1) on success, or a negative + * Returns: the number of bytes transferred (1) on success, or a negative * error code on failure. */ static inline ssize_t drm_dp_dpcd_readb(struct drm_dp_aux *aux, @@ -546,7 +547,7 @@ static inline ssize_t drm_dp_dpcd_readb( * @offset: address of the register to write * @value: value to write to the register * - * Returns the number of bytes transferred (1) on success, or a negative + * Returns: the number of bytes transferred (1) on success, or a negative * error code on failure. */ static inline ssize_t drm_dp_dpcd_writeb(struct drm_dp_aux *aux, @@ -714,7 +715,7 @@ enum drm_dp_quirk { * @desc: Device descriptor filled by drm_dp_read_desc() * @quirk: Quirk to query for * - * Return true if DP device identified by @desc has @quirk. + * Returns: %true if DP device identified by @desc has @quirk. */ static inline bool drm_dp_has_quirk(const struct drm_dp_desc *desc, enum drm_dp_quirk quirk)
Fix a struct member name in &struct drm_dp_as_sdp. Add Returns: kernel-doc syntax for 4 functions. In the Returns: sections, spell "%true" and "%false" consistently. Fixes these kernel-doc warnings: drm_dp_helper.h:126: warning: Function parameter or struct member 'mode' not described in 'drm_dp_as_sdp' drm_dp_helper.h:126: warning: Excess struct member 'operation_mode' description in 'drm_dp_as_sdp' drm_dp_helper.h:237: warning: No description found for return value of 'drm_dp_dsc_sink_supports_format' drm_dp_helper.h:539: warning: No description found for return value of 'drm_dp_dpcd_readb' drm_dp_helper.h:554: warning: No description found for return value of 'drm_dp_dpcd_writeb' drm_dp_helper.h:721: warning: No description found for return value of 'drm_dp_has_quirk' Signed-off-by: Randy Dunlap <rdunlap@infradead.org> --- Cc: David Airlie <airlied@gmail.com> Cc: Daniel Vetter <daniel@ffwll.ch> Cc: dri-devel@lists.freedesktop.org Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com> Cc: Maxime Ripard <mripard@kernel.org> Cc: Thomas Zimmermann <tzimmermann@suse.de> include/drm/display/drm_dp_helper.h | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-)