[media] docs-rst: improve the kAPI documentation for the mediactl

There are several issues on the documentation:
  - the media.h header were not properly referenced;
  - verbatim expressions were not properly marked as such;
  - struct member references were wrong;
  - some notes were not using the right markup;
  - a comment that were moved to the kernel-doc markup were
    duplicated as a comment inside the struct media_entity;
  - some args were not pointing to the struct they're using;
  - macros weren't documented.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>