And move the documenation we alreay have into kerneldoc, plus a bit of
polish while at it.

v2:
- Ditch FIXME from commit message, I've resolved that already before
  sending out the first version.
- Put the legacy DRIVER_ flags at the end (Sam).

Cc: Sam Ravnborg <sam@ravnborg.org>
Reviewed-by: Emil Velikov <emil.velikov@collabora.com>
Reviewed-by: Sam Ravnborg <sam@ravnborg.org>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20190129104248.26607-2-daniel.vetter@ffwll.ch