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

[Randy Dunlap]

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
  *
  * 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.
  */