[1/2] kernel-doc: Add unary operator * to $type_param_ref

Commit Message

Akira Yokosawa Feb. 27, 2024, 5:03 a.m. UTC

In kernel-doc comments, unary operator * collides with Sphinx/
docutil's markdown for emphasizing.

This resulted in additional warnings from "make htmldocs":

    WARNING: Inline emphasis start-string without end-string.

, as reported recently [1].

Those have been worked around either by escaping * (like \*param) or by
using inline-literal form of ``*param``, both of which are specific
to Sphinx/docutils.

Such workarounds are against the kenrel-doc's ideal and should better
be avoided.

Instead, add "*" to the list of unary operators kernel-doc recognizes
and make the form of *@param available in kernel-doc comments.

Reported-by: Stephen Rothwell <[e-mail]>
Link: [1] https://lore.kernel.org/r/[e-mail]/
Acked-by: Christoph Hellwig <[e-mail]>
Signed-off-by: Akira Yokosawa <[e-mail]>
Cc: Jonathan Corbet <[e-mail]>
Cc: Mauro Carvalho Chehab <[e-mail]>
---
Note for Chandan

As both of patches 1/2 and 2/2 are needed to resolve the warning from
Sphinx which commit d7468609ee0f ("shmem: export shmem_get_folio") in
the xfs tree introduced, I'd like you to pick them up.

        Thanks, Akira
---
 scripts/kernel-doc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)


base-commit: 4b2f459d86252619448455013f581836c8b1b7da

Comments

Jonathan Corbet Feb. 28, 2024, 10:40 p.m. UTC | #1

Akira Yokosawa <[e-mail]> writes:

> In kernel-doc comments, unary operator * collides with Sphinx/
> docutil's markdown for emphasizing.
>
> This resulted in additional warnings from "make htmldocs":
>
>     WARNING: Inline emphasis start-string without end-string.
>
> , as reported recently [1].
>
> Those have been worked around either by escaping * (like \*param) or by
> using inline-literal form of ``*param``, both of which are specific
> to Sphinx/docutils.
>
> Such workarounds are against the kenrel-doc's ideal and should better
> be avoided.
>
> Instead, add "*" to the list of unary operators kernel-doc recognizes
> and make the form of *@param available in kernel-doc comments.
>
> Reported-by: Stephen Rothwell <[e-mail]>
> Link: [1] https://lore.kernel.org/r/[e-mail]/
> Acked-by: Christoph Hellwig <[e-mail]>
> Signed-off-by: Akira Yokosawa <[e-mail]>
> Cc: Jonathan Corbet <[e-mail]>
> Cc: Mauro Carvalho Chehab <[e-mail]>
> ---
> Note for Chandan
>
> As both of patches 1/2 and 2/2 are needed to resolve the warning from
> Sphinx which commit d7468609ee0f ("shmem: export shmem_get_folio") in
> the xfs tree introduced, I'd like you to pick them up.

This change seems fine to me; I can't make it break anything.  I can't
apply the mm patch, so either they both get picked up on the other side
or we split them (which we could do, nothing would be any more broken
that way).  For the former case:

Acked-by: Jonathan Corbet <[e-mail]>

Thanks,

jon

Darrick J. Wong Feb. 28, 2024, 11:47 p.m. UTC | #2

On Wed, Feb 28, 2024 at 03:40:05PM -0700, Jonathan Corbet wrote:
> Akira Yokosawa <[e-mail]> writes:
> 
> > In kernel-doc comments, unary operator * collides with Sphinx/
> > docutil's markdown for emphasizing.
> >
> > This resulted in additional warnings from "make htmldocs":
> >
> >     WARNING: Inline emphasis start-string without end-string.
> >
> > , as reported recently [1].
> >
> > Those have been worked around either by escaping * (like \*param) or by
> > using inline-literal form of ``*param``, both of which are specific
> > to Sphinx/docutils.
> >
> > Such workarounds are against the kenrel-doc's ideal and should better
> > be avoided.
> >
> > Instead, add "*" to the list of unary operators kernel-doc recognizes
> > and make the form of *@param available in kernel-doc comments.
> >
> > Reported-by: Stephen Rothwell <[e-mail]>
> > Link: [1] https://lore.kernel.org/r/[e-mail]/
> > Acked-by: Christoph Hellwig <[e-mail]>
> > Signed-off-by: Akira Yokosawa <[e-mail]>
> > Cc: Jonathan Corbet <[e-mail]>
> > Cc: Mauro Carvalho Chehab <[e-mail]>
> > ---
> > Note for Chandan
> >
> > As both of patches 1/2 and 2/2 are needed to resolve the warning from
> > Sphinx which commit d7468609ee0f ("shmem: export shmem_get_folio") in
> > the xfs tree introduced, I'd like you to pick them up.
> 
> This change seems fine to me; I can't make it break anything.  I can't
> apply the mm patch, so either they both get picked up on the other side
> or we split them (which we could do, nothing would be any more broken
> that way).  For the former case:
> 
> Acked-by: Jonathan Corbet <[e-mail]>

Seeing as the changes came through the XFS tree, I second the notion of
pushing this via the xfs for-next.

--D

> Thanks,
> 
> jon
>

Patch

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e8aefd258a29..d2f3fa3505c6 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -64,7 +64,7 @@  my $type_constant = '\b``([^\`]+)``\b';
 my $type_constant2 = '\%([-_\w]+)';
 my $type_func = '(\w+)\(\)';
 my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
-my $type_param_ref = '([\!~]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
+my $type_param_ref = '([\!~\*]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
 my $type_fp_param = '\@(\w+)\(\)';  # Special RST handling for func ptr params
 my $type_fp_param2 = '\@(\w+->\S+)\(\)';  # Special RST handling for structs with func ptr params
 my $type_env = '(\$\w+)';