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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Wed, Feb 28, 2024 at 03:40:05PM -0700, Jonathan Corbet wrote:
> Akira Yokosawa <akiyks@xxxxxxxxx> 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@xxxxxxxxxxxxxxxx>
> > Link: [1] https://lore.kernel.org/r/20240223153636.41358be5@xxxxxxxxxxxxxxxx/
> > Acked-by: Christoph Hellwig <hch@xxxxxx>
> > Signed-off-by: Akira Yokosawa <akiyks@xxxxxxxxx>
> > Cc: Jonathan Corbet <corbet@xxxxxxx>
> > Cc: Mauro Carvalho Chehab <mchehab@xxxxxxxxxx>
> > ---
> > 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@xxxxxxx>

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

--D

> Thanks,
> 
> jon
> 




[Index of Archives]     [XFS Filesystem Development (older mail)]     [Linux Filesystem Development]     [Linux Audio Users]     [Yosemite Trails]     [Linux Kernel]     [Linux RAID]     [Linux SCSI]


  Powered by Linux