diff --git a/include/drm/drm_vblank.h b/include/drm/drm_vblank.h
index 848b463a0af5..425ad80ed2ac 100644
--- a/include/drm/drm_vblank.h
+++ b/include/drm/drm_vblank.h
@@ -55,8 +55,24 @@ struct drm_pending_vblank_event {
 	 * @event: Actual event which will be sent to userspace.
 	 */
 	union {
+		/**
+		 * @event.base: DRM event base class.
+		 */
 		struct drm_event base;
+
+		/**
+		 * @event.vbl:
+		 *
+		 * Event payload for vblank events, requested through
+		 * either the MODE_PAGE_FLIP or MODE_ATOMIC IOCTL. Also
+		 * generated by the legacy WAIT_VBLANK IOCTL, but new userspace
+		 * should use MODE_QUEUE_SEQUENCE and &event.seq instead.
+		 */
 		struct drm_event_vblank vbl;
+
+		/**
+		 * @event.seq: Event payload for the MODE_QUEUEU_SEQUENCE IOCTL.
+		 */
 		struct drm_event_crtc_sequence seq;
 	} event;
 };