Re: [PATCH v12 5/9] media: Documentation: uapi: Add qcom-camss ISP params documentation

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] media: Documentation: Sphinx indentation errors via qcom-camss-config.h
--

commit a20a54d2387cdb60e4b3cbece3fab3f39bdd075e
Author: Loic Poulain <loic.poulain@oss.qualcomm.com>

media: Documentation: uapi: Add qcom-camss ISP params documentation

This commit adds documentation for the Qualcomm CAMSS ISP parameters metadata
format (V4L2_META_FMT_QCOM_ISP_PARAMS) and wires
include/uapi/linux/qcom-camss-config.h into the Sphinx documentation build via
a kernel-doc directive.

> diff --git a/Documentation/userspace-api/media/v4l/metafmt-qcom-isp.rst b/Documentation/userspace-api/media/v4l/metafmt-qcom-isp.rst
> new file mode 100644
> index 0000000000000..da0dd9b0884ea
> --- /dev/null
> +++ b/Documentation/userspace-api/media/v4l/metafmt-qcom-isp.rst

[ ... ]

> +	/* Identity curve (pass-through, gamma 1.0) */
> +	for (unsigned int i = 0; i < CAMSS_GAMMA_LUT_SIZE; i++)
> +		gamma->glut[i] = gamma->blut[i] = gamma->rlut[i] = i;
> +
> +Qualcomm CAMSS ISP uAPI data types
> +==================================
> +
> +.. kernel-doc:: include/uapi/linux/qcom-camss-config.h

[Severity: Low]
Does wiring include/uapi/linux/qcom-camss-config.h into the documentation
build via this kernel-doc directive trigger Sphinx unexpected indentation
errors during make htmldocs?

In include/uapi/linux/qcom-camss-config.h, the kernel-doc comment for
struct camss_params_wb_gain has an indented numbered list immediately
following a two-line paragraph without a blank comment line in between:

 * Implements the CLC_WB pipeline module.  The pipeline applies three
 * sequential operations per channel:
 *   1. Subtract sub-offset (black-level subtraction)
 *   2. Multiply by gain    (colour balance)
 *   3. Add add-offset      (output pedestal)

Similarly, in struct camss_params_chroma_enhan, two multi-line paragraphs
are followed immediately by indented lines without a blank comment line:

 * RGB2Cb - Chroma (Cb) coefficients
 * Cb = a x ((B - G) + b(R - G)) + KCb
 * with:
 *   a = ap, when (B-G) + b(R-G) > 0; a = am, when (B-G) + b(R-G) ≤ 0;
 *   b = bp when (R-G) > 0; b = bm when (R-G) ≤ 0

and:

 * RGB2Cr - Chroma (Cr) coefficients:
 * Cr = c x ((R - G) + d(B - G)) + KCr
 * with:
 *   c = cp, when (R-G) + d(B-G) > 0; c = cm, when (R-G) + d(B-G) ≤ 0
 *   d = dp when (B-G) > 0; d = dm when (B-G) ≤ 0

When docutils parses the extracted reStructuredText, an indented line
immediately following a multi-line flush-left paragraph without an
intervening blank line raises UnexpectedIndentationError.

Also in include/uapi/linux/qcom-camss-config.h, the unprefixed RGB2Y,
RGB2Cb, and RGB2Cr paragraphs placed between member descriptions in
struct camss_params_chroma_enhan get appended to the trailing Description
section by kernel-doc, and the single-colon indented blocks in
struct camss_params_color_correct and struct camss_params_gamma are parsed
as reStructuredText definition lists rather than literal blocks because
they use ":" instead of "::".

Should the kernel-doc comments in include/uapi/linux/qcom-camss-config.h
be adjusted so that make htmldocs builds cleanly and renders these blocks
as intended?

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261102-camss-isp-ope-v12-0-702254689feb@oss.qualcomm.com?part=5