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

[Randy Dunlap]

Hi,

On 5/20/24 3:39 AM, Dmitry Baryshkov wrote:
> On Wed, May 15, 2024 at 05:26:52PM -0700, Randy Dunlap wrote:
>> Add @width and @height descriptions for &struct drm_plane_size_hint
>> along with a reference to more info.
>>
>> Add a short description for &struct drm_mode_closefb.
>>
>> Change 7 macros not to be marked as kernel-doc notation to prevent
>> warnings.
>>
>> Fixes these kernel-doc warnings:
>>
>> drm_mode.h:877: warning: Function parameter or struct member 'width' not described in 'drm_plane_size_hint'
>> drm_mode.h:877: warning: Function parameter or struct member 'height' not described in 'drm_plane_size_hint'
>> drm_mode.h:969: warning: missing initial short description on line:
>>  * DRM_MODE_PAGE_FLIP_EVENT
>> drm_mode.h:977: warning: missing initial short description on line:
>>  * DRM_MODE_PAGE_FLIP_ASYNC
>> drm_mode.h:998: warning: missing initial short description on line:
>>  * DRM_MODE_PAGE_FLIP_FLAGS
>> drm_mode.h:1108: warning: missing initial short description on line:
>>  * DRM_MODE_ATOMIC_TEST_ONLY
>> drm_mode.h:1118: warning: missing initial short description on line:
>>  * DRM_MODE_ATOMIC_NONBLOCK
>> drm_mode.h:1127: warning: missing initial short description on line:
>>  * DRM_MODE_ATOMIC_ALLOW_MODESET
>> drm_mode.h:1149: warning: missing initial short description on line:
>>  * DRM_MODE_ATOMIC_FLAGS
>> drm_mode.h:1358: warning: missing initial short description on line:
>>  * struct drm_mode_closefb
>>
>> 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/uapi/drm/drm_mode.h |   21 ++++++++++++---------
>>  1 file changed, 12 insertions(+), 9 deletions(-)
>>
>> diff -- a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
>> --- a/include/uapi/drm/drm_mode.h
>> +++ b/include/uapi/drm/drm_mode.h
>> @@ -867,9 +867,12 @@ struct drm_color_lut {
>>  
>>  /**
>>   * struct drm_plane_size_hint - Plane size hints
>> + * @width: recommended plane width (no scaling)
>> + * @height: recommended plane height (no scaling)
>>   *
>>   * The plane SIZE_HINTS property blob contains an
>> - * array of struct drm_plane_size_hint.
>> + * array of struct drm_plane_size_hint as described in
>> + * "DOC: standard plane properties".
>>   */
>>  struct drm_plane_size_hint {
>>  	__u16 width;
>> @@ -962,7 +965,7 @@ struct hdr_output_metadata {
>>  	};
>>  };
>>  
>> -/**
>> +/*
>>   * DRM_MODE_PAGE_FLIP_EVENT
> 
> What about convering to the proper kerneldoc instead of dropping the
> kerneldoc part?

If someone with knowledge of these macros can provide the text that should
be there, I can add that info.

>>   *
>>   * Request that the kernel sends back a vblank event (see
>> @@ -970,7 +973,7 @@ struct hdr_output_metadata {
>>   * page-flip is done.
>>   */
>>  #define DRM_MODE_PAGE_FLIP_EVENT 0x01
>> -/**
>> +/*
>>   * DRM_MODE_PAGE_FLIP_ASYNC
>>   *
>>   * Request that the page-flip is performed as soon as possible, ie. with no
>> @@ -991,7 +994,7 @@ struct hdr_output_metadata {
>>  #define DRM_MODE_PAGE_FLIP_TARGET_RELATIVE 0x8
>>  #define DRM_MODE_PAGE_FLIP_TARGET (DRM_MODE_PAGE_FLIP_TARGET_ABSOLUTE | \
>>  				   DRM_MODE_PAGE_FLIP_TARGET_RELATIVE)
>> -/**
>> +/*
>>   * DRM_MODE_PAGE_FLIP_FLAGS
>>   *
>>   * Bitmask of flags suitable for &drm_mode_crtc_page_flip_target.flags.
>> @@ -1101,7 +1104,7 @@ struct drm_mode_destroy_dumb {
>>  	__u32 handle;
>>  };
>>  
>> -/**
>> +/*
>>   * DRM_MODE_ATOMIC_TEST_ONLY
>>   *
>>   * Do not apply the atomic commit, instead check whether the hardware supports
>> @@ -1111,7 +1114,7 @@ struct drm_mode_destroy_dumb {
>>   * commits.
>>   */
>>  #define DRM_MODE_ATOMIC_TEST_ONLY 0x0100
>> -/**
>> +/*
>>   * DRM_MODE_ATOMIC_NONBLOCK
>>   *
>>   * Do not block while applying the atomic commit. The &DRM_IOCTL_MODE_ATOMIC
>> @@ -1120,7 +1123,7 @@ struct drm_mode_destroy_dumb {
>>   * applied before retuning.
>>   */
>>  #define DRM_MODE_ATOMIC_NONBLOCK  0x0200
>> -/**
>> +/*
>>   * DRM_MODE_ATOMIC_ALLOW_MODESET
>>   *
>>   * Allow the update to result in temporary or transient visible artifacts while
>> @@ -1142,7 +1145,7 @@ struct drm_mode_destroy_dumb {
>>   */
>>  #define DRM_MODE_ATOMIC_ALLOW_MODESET 0x0400
>>  
>> -/**
>> +/*
>>   * DRM_MODE_ATOMIC_FLAGS
>>   *
>>   * Bitfield of flags accepted by the &DRM_IOCTL_MODE_ATOMIC IOCTL in
>> @@ -1352,7 +1355,7 @@ struct drm_mode_rect {
>>  };
>>  
>>  /**
>> - * struct drm_mode_closefb
>> + * struct drm_mode_closefb - ioctl struct to close a framebuffer
>>   * @fb_id: Framebuffer ID.
>>   * @pad: Must be zero.
>>   */
> 

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