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

[Rodrigo Vivi <rodrigo.vivi@intel.com>]

On Fri, Mar 28, 2025 at 09:22:37PM +0200, Imre Deak wrote:
> 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.

doh! indeed! and I had already faced that and came to that conclusion in
another opportunity...

> Using that fix instead:
> 
> Reviewed-by: Imre Deak <imre.deak@intel.com>

sending v2 right now, thank you!

> 
> [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
> >