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

[Jonathan Corbet <corbet@lwn.net>]

Akira Yokosawa <akiyks@gmail.com> 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 <sfr@canb.auug.org.au>
> Link: [1] https://lore.kernel.org/r/20240223153636.41358be5@canb.auug.org.au/
> Acked-by: Christoph Hellwig <hch@lst.de>
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
> ---
> 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 <corbet@lwn.net>

Thanks,

jon