drm: polish function kerneldoc for drm_modes.[hc]

- Tune down yelling RETURNS.
- OCD align all the parameters the same.
- Add missing kerneldoc, which also means that we need to include the
  kerneldoc from the drm_modes.h header now.
- Add missing Returns: sections.
- General polish and clarification - especially the kerneldoc for the
  mode creation helpers seems to have been some good specimen of
  copypasta gone wrong.

All actual code changes have all been extracted into prep patches
since there was simply too much to polish.

v2: More polish for the command line modeline functions.
Reviewed-by: Alex Deucher <alexander.deucher@amd.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>

Documentation/DocBook/drm.tmpl

@@ -965,6 +965,7 @@ int max_width, max_height;</synopsis>
     </itemizedlist>
     <sect2>
       <title>Display Modes Function Reference</title>
+!Iinclude/drm/drm_modes.h
 !Edrivers/gpu/drm/drm_modes.c
     </sect2>
     <sect2>

include/drm/drm_modes.h

@@ -162,6 +162,14 @@ struct drm_cmdline_mode {
 	enum drm_connector_force force;
 };
 
+/**
+ * drm_mode_is_stereo - check for stereo mode flags
+ * @mode: drm_display_mode to check
+ *
+ * Returns:
+ * True if the mode is one of the stereo modes (like side-by-side), false if
+ * not.
+ */
 static inline bool drm_mode_is_stereo(const struct drm_display_mode *mode)
 {
 	return mode->flags & DRM_MODE_FLAG_3D_MASK;