Merge tag 'docs/v5.10-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media

Pull documentation updates from Mauro Carvalho Chehab:
 "A series of patches addressing warnings produced by make htmldocs.
  This includes:

   - kernel-doc markup fixes

   - ReST fixes

   - Updates at the build system in order to support newer versions of
     the docs build toolchain (Sphinx)

  After this series, the number of html build warnings should reduce
  significantly, and building with Sphinx 3.1 or later should now be
  supported (although it is still recommended to use Sphinx 2.4.4).

  As agreed with Jon, I should be sending you a late pull request by the
  end of the merge window addressing remaining issues with docs build,
  as there are a number of warning fixes that depends on pull requests
  that should be happening along the merge window.

  The end goal is to have a clean htmldocs build on Kernel 5.10.

  PS. It should be noticed that Sphinx 3.0 is not currently supported,
  as it lacks support for C domain namespaces. Such feature, needed in
  order to document uAPI system calls with Sphinx 3.x, was added only on
  Sphinx 3.1"

* tag 'docs/v5.10-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (75 commits)
  PM / devfreq: remove a duplicated kernel-doc markup
  mm/doc: fix a literal block markup
  workqueue: fix a kernel-doc warning
  docs: virt: user_mode_linux_howto_v2.rst: fix a literal block markup
  Input: sparse-keymap: add a description for @sw
  rcu/tree: docs: document bkvcache new members at struct kfree_rcu_cpu
  nl80211: docs: add a description for s1g_cap parameter
  usb: docs: document altmode register/unregister functions
  kunit: test.h: fix a bad kernel-doc markup
  drivers: core: fix kernel-doc markup for dev_err_probe()
  docs: bio: fix a kerneldoc markup
  kunit: test.h: solve kernel-doc warnings
  block: bio: fix a warning at the kernel-doc markups
  docs: powerpc: syscall64-abi.rst: fix a malformed table
  drivers: net: hamradio: fix document location
  net: appletalk: Kconfig: Fix docs location
  dt-bindings: fix references to files converted to yaml
  memblock: get rid of a :c:type leftover
  math64.h: kernel-docs: Convert some markups into normal comments
  media: uAPI: buffer.rst: remove a left-over documentation
  ...

1 files changed, 6 insertions, 33 deletions

diff --git a/Documentation/userspace-api/media/v4l/diff-v4l.rst b/Documentation/userspace-api/media/v4l/diff-v4l.rst
index 3f7bac44377c..caa05fbbd396 100644
--- a/Documentation/userspace-api/media/v4l/diff-v4l.rst
+++ b/Documentation/userspace-api/media/v4l/diff-v4l.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
 
 .. _diff-v4l:
 
@@ -13,7 +14,6 @@ the much improved V4L2 API replaces the V4L API. The support for the old
 V4L calls were removed from Kernel, but the library :ref:`libv4l`
 supports the conversion of a V4L API system call into a V4L2 one.
 
-
 Opening and Closing Devices
 ===========================
 
@@ -32,7 +32,6 @@ recommend that V4L2 drivers by default register devices with the same
 numbers, but the system administrator can assign arbitrary minor numbers
 using driver module options. The major device number remains 81.
 
-
 .. _v4l-dev:
 
 .. flat-table:: V4L Device Types, Names and Numbers
@@ -53,14 +52,12 @@ using driver module options. The major device number remains 81.
       - ``/dev/vbi``, ``/dev/vbi0`` to ``/dev/vbi31``
       - 224-255
 
-
 V4L prohibits (or used to prohibit) multiple opens of a device file.
 V4L2 drivers *may* support multiple opens, see :ref:`open` for details
 and consequences.
 
 V4L drivers respond to V4L2 ioctls with an ``EINVAL`` error code.
 
-
 Querying Capabilities
 =====================
 
@@ -151,7 +148,6 @@ introduction.
       - ``-``
       - See above.
 
-
 The ``audios`` field was replaced by ``capabilities`` flag
 ``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or
 outputs. To determine their number applications can enumerate audio
@@ -164,7 +160,6 @@ were removed. Calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
 dimensions returns the closest size possible, taking into account the
 current video standard, cropping and scaling limitations.
 
-
 Video Sources
 =============
 
@@ -180,7 +175,6 @@ The ``channel`` field counting inputs was renamed to ``index``, the
 video input types were renamed as follows:
 
 
-
 .. flat-table::
     :header-rows:  1
     :stub-columns: 0
@@ -192,7 +186,6 @@ video input types were renamed as follows:
     * - ``VIDEO_TYPE_CAMERA``
       - ``V4L2_INPUT_TYPE_CAMERA``
 
-
 Unlike the ``tuners`` field expressing the number of tuners of this
 input, V4L2 assumes each video input is connected to at most one tuner.
 However a tuner can have more than one input, i. e. RF connectors, and a
@@ -216,7 +209,6 @@ addition together with the ``norm`` field and has been removed in the
 meantime. V4L2 has a similar, albeit more comprehensive approach to
 video standards, see :ref:`standard` for more information.
 
-
 Tuning
 ======
 
@@ -260,7 +252,6 @@ frequency where renamed to
 to a struct :c:type:`v4l2_frequency` instead of an
 unsigned long integer.
 
-
 .. _v4l-image-properties:
 
 Image Properties
@@ -274,7 +265,6 @@ replaced by V4L2 controls accessible with the
 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
 
 
-
 .. flat-table::
     :header-rows:  1
     :stub-columns: 0
@@ -292,7 +282,6 @@ replaced by V4L2 controls accessible with the
     * - ``whiteness``
       - ``V4L2_CID_WHITENESS``
 
-
 The V4L picture controls are assumed to range from 0 to 65535 with no
 particular reset value. The V4L2 API permits arbitrary limits and
 defaults which can be queried with the
@@ -306,7 +295,6 @@ of the image depth and others need not know. The ``palette`` field moved
 into the struct :c:type:`v4l2_pix_format`:
 
 
-
 .. flat-table::
     :header-rows:  1
     :stub-columns: 0
@@ -346,11 +334,9 @@ into the struct :c:type:`v4l2_pix_format`:
     * - ``VIDEO_PALETTE_YUV410P``
       - :ref:`V4L2_PIX_FMT_YVU410 <V4L2-PIX-FMT-YVU410>`
 
-
 V4L2 image formats are defined in :ref:`pixfmt`. The image format can
 be selected with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
 
-
 Audio
 =====
 
@@ -384,7 +370,6 @@ The following fields where replaced by V4L2 controls accessible with the
 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
 
 
-
 .. flat-table::
     :header-rows:  1
     :stub-columns: 0
@@ -400,7 +385,6 @@ The following fields where replaced by V4L2 controls accessible with the
     * - ``balance``
       - ``V4L2_CID_AUDIO_BALANCE``
 
-
 To determine which of these controls are supported by a driver V4L
 provides the ``flags`` ``VIDEO_AUDIO_VOLUME``, ``VIDEO_AUDIO_BASS``,
 ``VIDEO_AUDIO_TREBLE`` and ``VIDEO_AUDIO_BALANCE``. In the V4L2 API the
@@ -416,7 +400,6 @@ V4L2 API permits arbitrary limits and defaults which can be queried with
 the :ref:`VIDIOC_QUERYCTRL` ioctl. For general
 information about controls see :ref:`control`.
 
-
 Frame Buffer Overlay
 ====================
 
@@ -463,7 +446,6 @@ size is determined by ``w.width`` and ``w.height``.
 The ``VIDIOCCAPTURE`` ioctl to enable or disable overlay was renamed to
 :ref:`VIDIOC_OVERLAY`.
 
-
 Cropping
 ========
 
@@ -490,21 +472,19 @@ struct :c:type:`v4l2_window`. These structures are used to
 select a capture or overlay format with the
 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
 
-
 Reading Images, Memory Mapping
 ==============================
 
-
 Capturing using the read method
 -------------------------------
 
 There is no essential difference between reading images from a V4L or
-V4L2 device using the :ref:`read() <func-read>` function, however V4L2
+V4L2 device using the :c:func:`read()` function, however V4L2
 drivers are not required to support this I/O method. Applications can
 determine if the function is available with the
 :ref:`VIDIOC_QUERYCAP` ioctl. All V4L2 devices
 exchanging data with applications must support the
-:ref:`select() <func-select>` and :ref:`poll() <func-poll>`
+:c:func:`select()` and :c:func:`poll()`
 functions.
 
 To select an image format and size, V4L provides the ``VIDIOCSPICT`` and
@@ -517,7 +497,6 @@ negotiation ioctls :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
 
 For more information about the V4L2 read interface see :ref:`rw`.
 
-
 Capturing using memory mapping
 ------------------------------
 
@@ -528,7 +507,6 @@ read method. V4L2 supports memory mapping as well, with a few
 differences.
 
 
-
 .. flat-table::
     :header-rows:  1
     :stub-columns: 0
@@ -550,7 +528,7 @@ differences.
 	``VIDIOCGMBUF`` ioctl is available to query the number of buffers,
 	the offset of each buffer from the start of the virtual file, and
 	the overall amount of memory used, which can be used as arguments
-	for the :ref:`mmap() <func-mmap>` function.
+	for the :c:func:`mmap()` function.
       - Buffers are individually mapped. The offset and size of each
 	buffer can be determined with the
 	:ref:`VIDIOC_QUERYBUF` ioctl.
@@ -568,7 +546,7 @@ differences.
 	the incoming queue. Filled buffers are dequeued from the outgoing
 	queue with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. To wait
 	until filled buffers become available this function,
-	:ref:`select() <func-select>` or :ref:`poll() <func-poll>` can
+	:c:func:`select()` or :c:func:`poll()` can
 	be used. The :ref:`VIDIOC_STREAMON` ioctl
 	must be called once after enqueuing one or more buffers to start
 	capturing. Its counterpart
@@ -577,11 +555,9 @@ differences.
 	signal status, if known, with the
 	:ref:`VIDIOC_ENUMINPUT` ioctl.
 
-
 For a more in-depth discussion of memory mapping and examples, see
 :ref:`mmap`.
 
-
 Reading Raw VBI Data
 ====================
 
@@ -592,7 +568,6 @@ the V4L VBI interface. Reading from the device yields a raw VBI image
 with the following parameters:
 
 
-
 .. flat-table::
     :header-rows:  1
     :stub-columns: 0
@@ -616,7 +591,6 @@ with the following parameters:
     * - flags
       - 0
 
-
 Undocumented in the V4L specification, in Linux 2.3 the
 ``VIDIOCGVBIFMT`` and ``VIDIOCSVBIFMT`` ioctls using struct
 ``vbi_format`` were added to determine the VBI image
@@ -630,11 +604,10 @@ remaining fields are probably equivalent to struct
 
 Apparently only the Zoran (ZR 36120) driver implements these ioctls. The
 semantics differ from those specified for V4L2 in two ways. The
-parameters are reset on :ref:`open() <func-open>` and
+parameters are reset on :c:func:`open()` and
 ``VIDIOCSVBIFMT`` always returns an ``EINVAL`` error code if the parameters
 are invalid.
 
-
 Miscellaneous
 =============