| Message ID | b3657e96ea87a5803ed27d1cc0d9fa44b2f164cf.1657699522.git.mchehab@kernel.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | drm/i915: fix kernel-doc issues | expand |
On Wed, Jul 13, 2022 at 09:12:06AM +0100, Mauro Carvalho Chehab wrote: > Preserving ascii artwork on kernel-docs is tricky, as it needs > to respect both the Sphinx rules and be properly parsed by > kernel-doc script. > > The Sphinx syntax require code-blocks, which is: > > :: > > followed by a blank line and indented lines. > > But kernel-doc only works fine if the first and the last line > are indented with the same amount of spaces. > > Also, a "\" at the end means that the next line should be merged > with the first one. my first reaction was: "do we really need those new empty ( ) blocks?" Then I read this ;) Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com> > > Change the ascii artwork to be on code-blocks, starting all > lines at the same characters and not ending with a backslash. > > Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org> > --- > > To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. > See [PATCH v2 00/39] at: https://lore.kernel.org/all/cover.1657699522.git.mchehab@kernel.org/ > > drivers/gpu/drm/i915/intel_pm.c | 33 ++++++++++++++++++--------------- > 1 file changed, 18 insertions(+), 15 deletions(-) > > diff --git a/drivers/gpu/drm/i915/intel_pm.c b/drivers/gpu/drm/i915/intel_pm.c > index f06babdb3a8c..d3393752b04b 100644 > --- a/drivers/gpu/drm/i915/intel_pm.c > +++ b/drivers/gpu/drm/i915/intel_pm.c > @@ -684,18 +684,20 @@ static const struct intel_watermark_params i845_wm_info = { > * FIFO is relatively small compared to the amount of data > * fetched. > * > - * The FIFO level vs. time graph might look something like: > + * The FIFO level vs. time graph might look something like:: > * > - * |\ |\ > - * | \ | \ > - * __---__---__ (- plane active, _ blanking) > - * -> time > + * ^ > + * | |\ |\ ( ) > + * | | \ | \ ( ) > + * | __---__---__ (- plane active, _ blanking) > + * +-------------------> time > * > - * or perhaps like this: > + * or perhaps like this:: > * > - * |\|\ |\|\ > - * __----__----__ (- plane active, _ blanking) > - * -> time > + * ^ > + * | |\|\ |\|\ ( ) > + * | __----__----__ (- plane active, _ blanking) > + * +-------------------> time > * > * Returns: > * The watermark in bytes > @@ -731,13 +733,14 @@ static unsigned int intel_wm_method1(unsigned int pixel_rate, > * FIFO is relatively large compared to the amount of data > * fetched. > * > - * The FIFO level vs. time graph might look something like: > + * The FIFO level vs. time graph might look something like:: > * > - * |\___ |\___ > - * | \___ | \___ > - * | \ | \ > - * __ --__--__--__--__--__--__ (- plane active, _ blanking) > - * -> time > + * ^ > + * | |\___ |\___ ( ) > + * | | \___ | \___ ( ) > + * | | \ | \ ( ) > + * | __ --__--__--__--__--__--__ (- plane active, _ blanking) > + * +---------------------------------> time > * > * Returns: > * The watermark in bytes > -- > 2.36.1 >
On Tue, 9 Aug 2022 05:55:10 -0400 Rodrigo Vivi <rodrigo.vivi@intel.com> wrote: > On Wed, Jul 13, 2022 at 09:12:06AM +0100, Mauro Carvalho Chehab wrote: > > Preserving ascii artwork on kernel-docs is tricky, as it needs > > to respect both the Sphinx rules and be properly parsed by > > kernel-doc script. > > > > The Sphinx syntax require code-blocks, which is: > > > > :: > > > > followed by a blank line and indented lines. > > > > But kernel-doc only works fine if the first and the last line > > are indented with the same amount of spaces. > > > > Also, a "\" at the end means that the next line should be merged > > with the first one. > > my first reaction was: "do we really need those new empty ( ) blocks?" > > Then I read this ;) Yeah, it is tricky to get it right, due to kernel-doc + Sphinx here. Also, I bet that this would be needed even for ReST files with C code on it, as it is likely the C domain encoding at Sphinx that handles continuation lines with "\" at the end... > > Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com> > > > > > Change the ascii artwork to be on code-blocks, starting all > > lines at the same characters and not ending with a backslash. > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org> > > --- > > > > To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. > > See [PATCH v2 00/39] at: https://lore.kernel.org/all/cover.1657699522.git.mchehab@kernel.org/ > > > > drivers/gpu/drm/i915/intel_pm.c | 33 ++++++++++++++++++--------------- > > 1 file changed, 18 insertions(+), 15 deletions(-) > > > > diff --git a/drivers/gpu/drm/i915/intel_pm.c b/drivers/gpu/drm/i915/intel_pm.c > > index f06babdb3a8c..d3393752b04b 100644 > > --- a/drivers/gpu/drm/i915/intel_pm.c > > +++ b/drivers/gpu/drm/i915/intel_pm.c > > @@ -684,18 +684,20 @@ static const struct intel_watermark_params i845_wm_info = { > > * FIFO is relatively small compared to the amount of data > > * fetched. > > * > > - * The FIFO level vs. time graph might look something like: > > + * The FIFO level vs. time graph might look something like:: > > * > > - * |\ |\ > > - * | \ | \ > > - * __---__---__ (- plane active, _ blanking) > > - * -> time > > + * ^ > > + * | |\ |\ ( ) > > + * | | \ | \ ( ) > > + * | __---__---__ (- plane active, _ blanking) > > + * +-------------------> time > > * > > - * or perhaps like this: > > + * or perhaps like this:: > > * > > - * |\|\ |\|\ > > - * __----__----__ (- plane active, _ blanking) > > - * -> time > > + * ^ > > + * | |\|\ |\|\ ( ) > > + * | __----__----__ (- plane active, _ blanking) > > + * +-------------------> time > > * > > * Returns: > > * The watermark in bytes > > @@ -731,13 +733,14 @@ static unsigned int intel_wm_method1(unsigned int pixel_rate, > > * FIFO is relatively large compared to the amount of data > > * fetched. > > * > > - * The FIFO level vs. time graph might look something like: > > + * The FIFO level vs. time graph might look something like:: > > * > > - * |\___ |\___ > > - * | \___ | \___ > > - * | \ | \ > > - * __ --__--__--__--__--__--__ (- plane active, _ blanking) > > - * -> time > > + * ^ > > + * | |\___ |\___ ( ) > > + * | | \___ | \___ ( ) > > + * | | \ | \ ( ) > > + * | __ --__--__--__--__--__--__ (- plane active, _ blanking) > > + * +---------------------------------> time > > * > > * Returns: > > * The watermark in bytes > > -- > > 2.36.1 > >
diff --git a/drivers/gpu/drm/i915/intel_pm.c b/drivers/gpu/drm/i915/intel_pm.c index f06babdb3a8c..d3393752b04b 100644 --- a/drivers/gpu/drm/i915/intel_pm.c +++ b/drivers/gpu/drm/i915/intel_pm.c @@ -684,18 +684,20 @@ static const struct intel_watermark_params i845_wm_info = { * FIFO is relatively small compared to the amount of data * fetched. * - * The FIFO level vs. time graph might look something like: + * The FIFO level vs. time graph might look something like:: * - * |\ |\ - * | \ | \ - * __---__---__ (- plane active, _ blanking) - * -> time + * ^ + * | |\ |\ ( ) + * | | \ | \ ( ) + * | __---__---__ (- plane active, _ blanking) + * +-------------------> time * - * or perhaps like this: + * or perhaps like this:: * - * |\|\ |\|\ - * __----__----__ (- plane active, _ blanking) - * -> time + * ^ + * | |\|\ |\|\ ( ) + * | __----__----__ (- plane active, _ blanking) + * +-------------------> time * * Returns: * The watermark in bytes @@ -731,13 +733,14 @@ static unsigned int intel_wm_method1(unsigned int pixel_rate, * FIFO is relatively large compared to the amount of data * fetched. * - * The FIFO level vs. time graph might look something like: + * The FIFO level vs. time graph might look something like:: * - * |\___ |\___ - * | \___ | \___ - * | \ | \ - * __ --__--__--__--__--__--__ (- plane active, _ blanking) - * -> time + * ^ + * | |\___ |\___ ( ) + * | | \___ | \___ ( ) + * | | \ | \ ( ) + * | __ --__--__--__--__--__--__ (- plane active, _ blanking) + * +---------------------------------> time * * Returns: * The watermark in bytes
Preserving ascii artwork on kernel-docs is tricky, as it needs to respect both the Sphinx rules and be properly parsed by kernel-doc script. The Sphinx syntax require code-blocks, which is: :: followed by a blank line and indented lines. But kernel-doc only works fine if the first and the last line are indented with the same amount of spaces. Also, a "\" at the end means that the next line should be merged with the first one. Change the ascii artwork to be on code-blocks, starting all lines at the same characters and not ending with a backslash. Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org> --- To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH v2 00/39] at: https://lore.kernel.org/all/cover.1657699522.git.mchehab@kernel.org/ drivers/gpu/drm/i915/intel_pm.c | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-)