Hi all,
After merging the xfs tree, today's linux-next build (htmldocs) produced
this warning:
Documentation/core-api/mm-api:130: mm/shmem.c:2155: WARNING: Inline emphasis start-string without end-string.
Documentation/core-api/mm-api:130: mm/shmem.c:2156: WARNING: Inline emphasis start-string without end-string.
Introduced by commit
d7468609ee0f ("shmem: export shmem_get_folio")
--
Cheers,
Stephen Rothwell
On Fri, Feb 23, 2024 at 03:36:36PM +1100, Stephen Rothwell wrote:
> Hi all,
>
> After merging the xfs tree, today's linux-next build (htmldocs) produced
> this warning:
>
> Documentation/core-api/mm-api:130: mm/shmem.c:2155: WARNING: Inline emphasis start-string without end-string.
> Documentation/core-api/mm-api:130: mm/shmem.c:2156: WARNING: Inline emphasis start-string without end-string.
Thanks for the headsup. Looks like kernel-doc doesn't like the
pointer dereferene * operator. Any good idea how to write this instead?
>
> Introduced by commit
>
> d7468609ee0f ("shmem: export shmem_get_folio")
>
> --
> Cheers,
> Stephen Rothwell
---end quoted text---
Em Fri, 23 Feb 2024 07:35:54 +0100
Christoph Hellwig <[email protected]> escreveu:
> On Fri, Feb 23, 2024 at 03:36:36PM +1100, Stephen Rothwell wrote:
> > Hi all,
> >
> > After merging the xfs tree, today's linux-next build (htmldocs) produced
> > this warning:
> >
> > Documentation/core-api/mm-api:130: mm/shmem.c:2155: WARNING: Inline emphasis start-string without end-string.
> > Documentation/core-api/mm-api:130: mm/shmem.c:2156: WARNING: Inline emphasis start-string without end-string.
>
> Thanks for the headsup. Looks like kernel-doc doesn't like the
> pointer dereferene * operator. Any good idea how to write this instead?
Asterisks there are used to do *italic* or **bold**. To have an
asterisk as-is, it needs to be escaped. This would work:
\*foo
but it is very weird for the ones reading the text file. So, what
we do instead for pointers is to escape the entire declaration, like:
``*inode``
``struct inode *inode``
I hope that helps.
Thanks,
Mauro
On Fri, Feb 23, 2024 at 09:55:09AM +0100, Mauro Carvalho Chehab wrote:
> but it is very weird for the ones reading the text file. So, what
> we do instead for pointers is to escape the entire declaration, like:
>
> ``*inode``
> ``struct inode *inode``
>
> I hope that helps.
In this case it says *foliop for an argument that is a double pointer
and the comment refers to what it point to. I'll see what I can do
there, but the whole italic and bold thing seems entirely pointless
for kerneldoc..
Hi,
On Fri, 23 Feb 2024 15:06:19 +0100, Christoph Hellwig wrote:
> On Fri, Feb 23, 2024 at 09:55:09AM +0100, Mauro Carvalho Chehab wrote:
>> but it is very weird for the ones reading the text file. So, what
>> we do instead for pointers is to escape the entire declaration, like:
>>
>> ``*inode``
>> ``struct inode *inode``
>>
>> I hope that helps.
>
> In this case it says *foliop for an argument that is a double pointer
> and the comment refers to what it point to. I'll see what I can do
> there, but the whole italic and bold thing seems entirely pointless
> for kerneldoc..
Indeed.
How about teaching kernel-doc unary "*" on param?
Substitution would look like:
(kernel-doc) (RST)
*@param -> ***param**
Sphinx detects double asterisk, starts strong emphasis, waits for
another double asterisk to appear, and stops strong emphasis.
Hence you would get boldface "*param" in pretty printed docs.
Diff below (against docs-next) should add a rule for param_deref
(only for RST).
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 136104804375..bdd6f3b489cc 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -65,7 +65,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+)';
--
And you would be able to write the kernel-doc comment in question
as follows:
diff --git a/mm/shmem.c b/mm/shmem.c
index 750ab1dcae27..0aad0d9a621b 100644
--- a/mm/shmem.c
+++ b/mm/shmem.c
@@ -2152,8 +2152,8 @@ static int shmem_get_folio_gfp(struct inode *inode, pgoff_t index,
* There is no need to reserve space before calling folio_mark_dirty().
*
* When no folio is found, the behavior depends on @sgp:
- * - for SGP_READ, *foliop is %NULL and 0 is returned
- * - for SGP_NOALLOC, *foliop is %NULL and -ENOENT is returned
+ * - for SGP_READ, *@foliop is %NULL and 0 is returned
+ * - for SGP_NOALLOC, *@foliop is %NULL and -ENOENT is returned
* - for all other flags a new folio is allocated, inserted into the
* page cache and returned locked in @foliop.
*
--
How does this approach sound to you?
Thanks, Akira
On Sat, Feb 24, 2024 at 06:07:28PM +0900, Akira Yokosawa wrote:
> How about teaching kernel-doc unary "*" on param?
That would be great!
>
> Substitution would look like:
>
> (kernel-doc) (RST)
> *@param -> ***param**
>
> Sphinx detects double asterisk, starts strong emphasis, waits for
> another double asterisk to appear, and stops strong emphasis.
> Hence you would get boldface "*param" in pretty printed docs.
>
> Diff below (against docs-next) should add a rule for param_deref
> (only for RST).
I'd love to go with this instead of working around the issue:
Acked-by: Christoph Hellwig <[email protected]>