[media] v4l2-fh.rst: add cross references and markups

Add cross-references with the kernel-doc functions/structs
and improve the markups.

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

diff --git a/Documentation/media/kapi/v4l2-fh.rst b/Documentation/media/kapi/v4l2-fh.rst
index f39374262d3ff3e06ecfe2081c0bd44426bc0bcb..a212698d5725bb25e1923ece6c664317ab11a3aa 100644 (file)
--- a/Documentation/media/kapi/v4l2-fh.rst
+++ b/Documentation/media/kapi/v4l2-fh.rst
@@ -1,27 +1,35 @@
 V4L2 File handlers
 ------------------
 
-struct v4l2_fh provides a way to easily keep file handle specific data
-that is used by the V4L2 framework. New drivers must use struct v4l2_fh
-since it is also used to implement priority handling (VIDIOC_G/S_PRIORITY).
+struct :c:type:`v4l2_fh` provides a way to easily keep file handle specific
+data that is used by the V4L2 framework.
 
-The users of v4l2_fh (in the V4L2 framework, not the driver) know
-whether a driver uses v4l2_fh as its file->private_data pointer by
-testing the V4L2_FL_USES_V4L2_FH bit in video_device->flags. This bit is
-set whenever v4l2_fh_init() is called.
+.. attention::
+       New drivers must use struct :c:type:`v4l2_fh`
+       since it is also used to implement priority handling
+       (:ref:`VIDIOC_G_PRIORITY`).
 
-struct v4l2_fh is allocated as a part of the driver's own file handle
-structure and file->private_data is set to it in the driver's open
+The users of :c:type:`v4l2_fh` (in the V4L2 framework, not the driver) know
+whether a driver uses :c:type:`v4l2_fh` as its ``file->private_data`` pointer
+by testing the ``V4L2_FL_USES_V4L2_FH`` bit in :c:type:`video_device`->flags.
+This bit is set whenever :cpp:func:`v4l2_fh_init` is called.
+
+struct :c:type:`v4l2_fh` is allocated as a part of the driver's own file handle
+structure and ``file->private_data`` is set to it in the driver's ``open()``
 function by the driver.
 
-In many cases the struct v4l2_fh will be embedded in a larger structure.
-In that case you should call v4l2_fh_init+v4l2_fh_add in open() and
-v4l2_fh_del+v4l2_fh_exit in release().
+In many cases the struct :c:type:`v4l2_fh` will be embedded in a larger
+structure. In that case you should call:
+
+#) :cpp:func:`v4l2_fh_init` and :cpp:func:`v4l2_fh_add` in ``open()``
+#) :cpp:func:`v4l2_fh_del` and :cpp:func:`v4l2_fh_exit` in ``release()``
 
 Drivers can extract their own file handle structure by using the container_of
-macro. Example:
+macro.
+
+Example:
 
-.. code-block:: none
+.. code-block:: c
 
        struct my_fh {
                int blah;
@@ -63,73 +71,66 @@ macro. Example:
                return 0;
        }
 
-Below is a short description of the v4l2_fh functions used:
+Below is a short description of the :c:type:`v4l2_fh` functions used:
 
-.. code-block:: none
+:cpp:func:`v4l2_fh_init <v4l2_fh_init>`
+(:c:type:`fh <v4l2_fh>`, :c:type:`vdev <video_device>`)
 
-       void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev)
 
-  Initialise the file handle. This *MUST* be performed in the driver's
-  v4l2_file_operations->open() handler.
+- Initialise the file handle. This **MUST** be performed in the driver's
+  :c:type:`v4l2_file_operations`->open() handler.
 
-.. code-block:: none
 
-       void v4l2_fh_add(struct v4l2_fh *fh)
+:cpp:func:`v4l2_fh_add <v4l2_fh_add>`
+(:c:type:`fh <v4l2_fh>`)
 
-  Add a v4l2_fh to video_device file handle list. Must be called once the
-  file handle is completely initialized.
+- Add a :c:type:`v4l2_fh` to :c:type:`video_device` file handle list.
+  Must be called once the file handle is completely initialized.
 
-.. code-block:: none
+:cpp:func:`v4l2_fh_del <v4l2_fh_del>`
+(:c:type:`fh <v4l2_fh>`)
 
-       void v4l2_fh_del(struct v4l2_fh *fh)
-
-  Unassociate the file handle from video_device(). The file handle
+- Unassociate the file handle from :c:type:`video_device`. The file handle
   exit function may now be called.
 
-.. code-block:: none
-
-       void v4l2_fh_exit(struct v4l2_fh *fh)
+:cpp:func:`v4l2_fh_exit <v4l2_fh_exit>`
+(:c:type:`fh <v4l2_fh>`)
 
-  Uninitialise the file handle. After uninitialisation the v4l2_fh
+- Uninitialise the file handle. After uninitialisation the :c:type:`v4l2_fh`
   memory can be freed.
 
 
-If struct v4l2_fh is not embedded, then you can use these helper functions:
+If struct :c:type:`v4l2_fh` is not embedded, then you can use these helper functions:
 
-.. code-block:: none
+:cpp:func:`v4l2_fh_open <v4l2_fh_open>`
+(struct file \*filp)
 
-       int v4l2_fh_open(struct file *filp)
+- This allocates a struct :c:type:`v4l2_fh`, initializes it and adds it to
+  the struct :c:type:`video_device` associated with the file struct.
 
-  This allocates a struct v4l2_fh, initializes it and adds it to the struct
-  video_device associated with the file struct.
+:cpp:func:`v4l2_fh_release <v4l2_fh_release>`
+(struct file \*filp)
 
-.. code-block:: none
-
-       int v4l2_fh_release(struct file *filp)
-
-  This deletes it from the struct video_device associated with the file
-  struct, uninitialised the v4l2_fh and frees it.
-
-These two functions can be plugged into the v4l2_file_operation's open() and
-release() ops.
+- This deletes it from the struct :c:type:`video_device` associated with the
+  file struct, uninitialised the :c:type:`v4l2_fh` and frees it.
 
+These two functions can be plugged into the v4l2_file_operation's ``open()``
+and ``release()`` ops.
 
 Several drivers need to do something when the first file handle is opened and
 when the last file handle closes. Two helper functions were added to check
-whether the v4l2_fh struct is the only open filehandle of the associated
-device node:
-
-.. code-block:: none
-
-       int v4l2_fh_is_singular(struct v4l2_fh *fh)
+whether the :c:type:`v4l2_fh` struct is the only open filehandle of the
+associated device node:
 
-  Returns 1 if the file handle is the only open file handle, else 0.
+:cpp:func:`v4l2_fh_is_singular <v4l2_fh_is_singular>`
+(:c:type:`fh <v4l2_fh>`)
 
-.. code-block:: none
+-  Returns 1 if the file handle is the only open file handle, else 0.
 
-       int v4l2_fh_is_singular_file(struct file *filp)
+:cpp:func:`v4l2_fh_is_singular_file <v4l2_fh_is_singular_file>`
+(struct file \*filp)
 
-  Same, but it calls v4l2_fh_is_singular with filp->private_data.
+- Same, but it calls v4l2_fh_is_singular with filp->private_data.
 
 
 V4L2 File Handler kAPI