media: docs: make V4L documents more compatible with Sphinx 3.1+

Sphinx 3.x broke support for the cdomain.py extension, as the
c domain code was rewritten. Due to that, the c tags need to
be re-written, in order to use the new c domain notation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Documentation/userspace-api/media/v4l/func-read.rst

@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
 
 .. _func-read:
 
@@ -11,7 +12,6 @@ Name
 
 v4l2-read - Read from a V4L2 device
 
-
 Synopsis
 ========
 
@@ -19,15 +19,13 @@ Synopsis
 
     #include <unistd.h>
 
-
 .. c:function:: ssize_t read( int fd, void *buf, size_t count )
-    :name: v4l2-read
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :ref:`open() <func-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``buf``
    Buffer to be filled
@@ -38,48 +36,48 @@ Arguments
 Description
 ===========
 
-:ref:`read() <func-read>` attempts to read up to ``count`` bytes from file
+:c:func:`read()` attempts to read up to ``count`` bytes from file
 descriptor ``fd`` into the buffer starting at ``buf``. The layout of the
 data in the buffer is discussed in the respective device interface
-section, see ##. If ``count`` is zero, :ref:`read() <func-read>` returns zero
+section, see ##. If ``count`` is zero, :c:func:`read()` returns zero
 and has no other results. If ``count`` is greater than ``SSIZE_MAX``,
 the result is unspecified. Regardless of the ``count`` value each
-:ref:`read() <func-read>` call will provide at most one frame (two fields)
+:c:func:`read()` call will provide at most one frame (two fields)
 worth of data.
 
-By default :ref:`read() <func-read>` blocks until data becomes available. When
-the ``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>`
+By default :c:func:`read()` blocks until data becomes available. When
+the ``O_NONBLOCK`` flag was given to the :c:func:`open()`
 function it returns immediately with an ``EAGAIN`` error code when no data
-is available. The :ref:`select() <func-select>` or
-:ref:`poll() <func-poll>` functions can always be used to suspend
+is available. The :c:func:`select()` or
+:c:func:`poll()` functions can always be used to suspend
 execution until data becomes available. All drivers supporting the
-:ref:`read() <func-read>` function must also support :ref:`select() <func-select>` and
-:ref:`poll() <func-poll>`.
+:c:func:`read()` function must also support :c:func:`select()` and
+:c:func:`poll()`.
 
 Drivers can implement read functionality in different ways, using a
 single or multiple buffers and discarding the oldest or newest frames
 once the internal buffers are filled.
 
-:ref:`read() <func-read>` never returns a "snapshot" of a buffer being filled.
+:c:func:`read()` never returns a "snapshot" of a buffer being filled.
 Using a single buffer the driver will stop capturing when the
 application starts reading the buffer until the read is finished. Thus
 only the period of the vertical blanking interval is available for
 reading, or the capture rate must fall below the nominal frame rate of
 the video standard.
 
-The behavior of :ref:`read() <func-read>` when called during the active picture
+The behavior of :c:func:`read()` when called during the active picture
 period or the vertical blanking separating the top and bottom field
 depends on the discarding policy. A driver discarding the oldest frames
 keeps capturing into an internal buffer, continuously overwriting the
 previously, not read frame, and returns the frame being received at the
-time of the :ref:`read() <func-read>` call as soon as it is complete.
+time of the :c:func:`read()` call as soon as it is complete.
 
 A driver discarding the newest frames stops capturing until the next
-:ref:`read() <func-read>` call. The frame being received at :ref:`read() <func-read>`
+:c:func:`read()` call. The frame being received at :c:func:`read()`
 time is discarded, returning the following frame instead. Again this
 implies a reduction of the capture rate to one half or less of the
 nominal frame rate. An example of this model is the video read mode of
-the bttv driver, initiating a DMA to user memory when :ref:`read() <func-read>`
+the bttv driver, initiating a DMA to user memory when :c:func:`read()`
 is called and returning when the DMA finished.
 
 In the multiple buffer model drivers maintain a ring of internal
@@ -94,14 +92,13 @@ the driver with the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
 however. The discarding policy is not reported and cannot be changed.
 For minimum requirements see :ref:`devices`.
 
-
 Return Value
 ============
 
 On success, the number of bytes read is returned. It is not an error if
 this number is smaller than the number of bytes requested, or the amount
 of data required for one frame. This may happen for example because
-:ref:`read() <func-read>` was interrupted by a signal. On error, -1 is
+:c:func:`read()` was interrupted by a signal. On error, -1 is
 returned, and the ``errno`` variable is set appropriately. In this case
 the next read will start at the beginning of a new frame. Possible error
 codes are:
@@ -129,5 +126,5 @@ EIO
     communicate with a remote device (USB camera etc.).
 
 EINVAL
-    The :ref:`read() <func-read>` function is not supported by this driver, not
+    The :c:func:`read()` function is not supported by this driver, not
     on this device, or generally not on this type of device.