Em Thu, 3 Dec 2020 11:52:29 +0100 Hans Verkuil <hverkuil-cisco@xxxxxxxxx> escreveu: > On 03/12/2020 11:49, Mauro Carvalho Chehab wrote: > > Em Thu, 26 Nov 2020 14:27:16 +0100 > > Hans Verkuil <hverkuil-cisco@xxxxxxxxx> 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@xxxxxxxxx> > >> --- > >> .../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. > > 'git grep struct.*:c:type Documentation' shows a lot of those incorrect > markups. Perhaps make a media-wide patch to fix this? Otherwise people > will just keep copy-and-pasting the same incorrect markup. Hmm... looking at Documentation/sphinx/parse-headers.pl, it seems that the logic is not declaring structs using a Sphinx3 compatible format, but, instead, using :c:type: everywhere. So, I guess I'll just merge those two patches as-is, and then work on a media-wide patchset. > > Regards, > > Hans > > > > > 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 > > > Thanks, Mauro
