Re: [PATCH] drm/i915/display: Fix htmldocs build

[Imre Deak <imre.deak@intel.com>]

On Fri, Mar 28, 2025 at 02:08:29PM -0400, Rodrigo Vivi wrote:
> Fixes a wrong documentation block indentation:
> 
> Documentation/gpu/i915:141: ./drivers/gpu/drm/i915/display/intel_hotplug.c:1080: ERROR: Unexpected indentation.
> Documentation/gpu/i915:141: ./drivers/gpu/drm/i915/display/intel_hotplug.c:1082: WARNING: Block quote ends without a blank line; unexpected unindent.
> 
> Fixes: 0d77a3e0ea90 ("drm/i915/hpd: Add support for blocking the IRQ handling on an HPD pin")
> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Closes: https://lore.kernel.org/intel-gfx/20250312232506.47451f83@canb.auug.org.au/
> Cc: Imre Deak <imre.deak@intel.com>
> Signed-off-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
> ---
>  drivers/gpu/drm/i915/display/intel_hotplug.c | 18 +++++++++---------
>  1 file changed, 9 insertions(+), 9 deletions(-)
> 
> diff --git a/drivers/gpu/drm/i915/display/intel_hotplug.c b/drivers/gpu/drm/i915/display/intel_hotplug.c
> index dce9cde03d70..0f5068d2389b 100644
> --- a/drivers/gpu/drm/i915/display/intel_hotplug.c
> +++ b/drivers/gpu/drm/i915/display/intel_hotplug.c
> @@ -1075,15 +1075,15 @@ static bool unblock_hpd_pin(struct intel_display *display, enum hpd_pin pin)
>   * Blocks the handling of HPD IRQs on the HPD pin of @encoder.
>   *
>   * On return:

The closest documentation I found about lists in a kernel-doc block is
the one for Sphinx at [1]. According to that an empty line is required
here (i.e. before the first list item) and then no need to add extra
indents for list items. Tested that now with 'make htmldocs' as well.
Using that fix instead:

Reviewed-by: Imre Deak <imre.deak@intel.com>

[1] https://ikerdocs-sphinx.readthedocs.io/syntax/lists.html

> - * - It's guaranteed that the blocked encoders' HPD pulse handler
> - *   (via intel_digital_port::hpd_pulse()) is not running.
> - * - The hotplug event handling (via intel_encoder::hotplug()) of an
> - *   HPD IRQ pending at the time this function is called may be still
> - *   running.
> - * - Detection on the encoder's connector (via
> - *   drm_connector_helper_funcs::detect_ctx(),
> - *   drm_connector_funcs::detect()) remains allowed, for instance as part of
> - *   userspace connector probing, or DRM core's connector polling.
> + *  - It's guaranteed that the blocked encoders' HPD pulse handler
> + *    (via intel_digital_port::hpd_pulse()) is not running.
> + *  - The hotplug event handling (via intel_encoder::hotplug()) of an
> + *    HPD IRQ pending at the time this function is called may be still
> + *    running.
> + *  - Detection on the encoder's connector (via
> + *    drm_connector_helper_funcs::detect_ctx(),
> + *    drm_connector_funcs::detect()) remains allowed, for instance as part of
> + *    userspace connector probing, or DRM core's connector polling.
>   *
>   * The call must be followed by calling intel_hpd_unblock(), or
>   * intel_hpd_clear_and_unblock().
> -- 
> 2.49.0
>