| Message ID | 20240516002652.6674-1-rdunlap@infradead.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | drm/mode: fix all kernel-doc warnings | expand |
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@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/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? > * > * 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. > */
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@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/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.
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 * * 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. */
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@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/uapi/drm/drm_mode.h | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-)