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

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

[Rodrigo Vivi]

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:
- * - 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

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

[Imre Deak]

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
> 

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

[Rodrigo Vivi]

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

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

[Rodrigo Vivi]

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.

v2: Use an empty line instead of changing block indentation (Imre)

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>
Reviewed-by: Imre Deak <imre.deak@intel.com>
Link: https://lore.kernel.org/r/20250328180829.25892-1-rodrigo.vivi@intel.com
Signed-off-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
---
 drivers/gpu/drm/i915/display/intel_hotplug.c | 1 +
 1 file changed, 1 insertion(+)

diff --git a/drivers/gpu/drm/i915/display/intel_hotplug.c b/drivers/gpu/drm/i915/display/intel_hotplug.c
index dce9cde03d70..6885e5a09079 100644
--- a/drivers/gpu/drm/i915/display/intel_hotplug.c
+++ b/drivers/gpu/drm/i915/display/intel_hotplug.c
@@ -1075,6 +1075,7 @@ 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:
+ *
  * - 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
-- 
2.49.0