Re: [PATCH 5/6] vidioc-g-ext-ctrls.rst: add missing 'struct' before the types

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Thu, 26 Nov 2020 14:27:16 +0100
Hans Verkuil <hverkuil-cisco@xs4all.nl> escreveu:

> Add 'struct' to clarify that these are pointers to structs.

This patch is actually wrong :-)

It is incompatible with Sphinx 3.

> 
> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
> ---
>  .../userspace-api/media/v4l/vidioc-g-ext-ctrls.rst | 14 +++++++-------
>  1 file changed, 7 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst
> index 726d6a97325f..5b1fc62ade0d 100644
> --- a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst
> +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst
> @@ -180,31 +180,31 @@ still cause this situation.
>        - ``p_u32``
>        - A pointer to a matrix control of unsigned 32-bit values. Valid if
>  	this control is of type ``V4L2_CTRL_TYPE_U32``.
> -    * - :c:type:`v4l2_area` *
> +    * - struct :c:type:`v4l2_area` *


See, with Sphinx 3, :c:type: can only be used for typedefs and defines.

The right markup for struct is:

	:c:struct:

Actually, due to automarkup.py extension, I would just rename them to:

	struct foo

And let the automarkup code to use the right markup, as it will ensure
that the proper dialect will be used, no matter what Sphinx version 
will be used to produce the docs.

So, I'll drop this patch from the series. I'll propose a new one
instead, after testing with multiple versions of Sphinx.

Regards,
Mauro



>        - ``p_area``
>        - A pointer to a struct :c:type:`v4l2_area`. Valid if this control is
>          of type ``V4L2_CTRL_TYPE_AREA``.
> -    * - :c:type:`v4l2_ctrl_h264_sps` *
> +    * - struct :c:type:`v4l2_ctrl_h264_sps` *
>        - ``p_h264_sps``
>        - A pointer to a struct :c:type:`v4l2_ctrl_h264_sps`. Valid if this control is
>          of type ``V4L2_CTRL_TYPE_H264_SPS``.
> -    * - :c:type:`v4l2_ctrl_h264_pps` *
> +    * - struct :c:type:`v4l2_ctrl_h264_pps` *
>        - ``p_h264_pps``
>        - A pointer to a struct :c:type:`v4l2_ctrl_h264_pps`. Valid if this control is
>          of type ``V4L2_CTRL_TYPE_H264_PPS``.
> -    * - :c:type:`v4l2_ctrl_h264_scaling_matrix` *
> +    * - struct :c:type:`v4l2_ctrl_h264_scaling_matrix` *
>        - ``p_h264_scaling_matrix``
>        - A pointer to a struct :c:type:`v4l2_ctrl_h264_scaling_matrix`. Valid if this control is
>          of type ``V4L2_CTRL_TYPE_H264_SCALING_MATRIX``.
> -    * - :c:type:`v4l2_ctrl_h264_pred_weights` *
> +    * - struct :c:type:`v4l2_ctrl_h264_pred_weights` *
>        - ``p_h264_pred_weights``
>        - A pointer to a struct :c:type:`v4l2_ctrl_h264_pred_weights`. Valid if this control is
>          of type ``V4L2_CTRL_TYPE_H264_PRED_WEIGHTS``.
> -    * - :c:type:`v4l2_ctrl_h264_slice_params` *
> +    * - struct :c:type:`v4l2_ctrl_h264_slice_params` *
>        - ``p_h264_slice_params``
>        - A pointer to a struct :c:type:`v4l2_ctrl_h264_slice_params`. Valid if this control is
>          of type ``V4L2_CTRL_TYPE_H264_SLICE_PARAMS``.
> -    * - :c:type:`v4l2_ctrl_h264_decode_params` *
> +    * - struct :c:type:`v4l2_ctrl_h264_decode_params` *
>        - ``p_h264_decode_params``
>        - A pointer to a struct :c:type:`v4l2_ctrl_h264_decode_params`. Valid if this control is
>          of type ``V4L2_CTRL_TYPE_H264_DECODE_PARAMS``.



Thanks,
Mauro