[PATCH] drm/display/dp: fix all kernel-doc warnings

[Randy Dunlap]

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 at infradead.org>
>>>> ---
>>>> Cc: David Airlie <airlied at gmail.com>
>>>> Cc: Daniel Vetter <daniel at ffwll.ch>
>>>> Cc: dri-devel at lists.freedesktop.org
>>>> Cc: Maarten Lankhorst <maarten.lankhorst at linux.intel.com>
>>>> Cc: Maxime Ripard <mripard at kernel.org>
>>>> Cc: Thomas Zimmermann <tzimmermann at 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
> 

-- 
#Randy
https://people.kernel.org/tglx/notes-about-netiquette
https://subspace.kernel.org/etiquette.html