Skip to contentSkip to conversation

linux-next: build warning after merge of the xfs tree

DISCUSSION Stephen Rothwell 4 participants 6 messages Feb 23, 2024 – Feb 26, 2024

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

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")

Signature · 2 lines
Cheers,
Stephen Rothwell
#1 lore raw
Quoted 7 lines · Stephen Rothwell

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?

Quoted 8 lines

Introduced by commit

d7468609ee0f ("shmem: export shmem_get_folio")

Signature · 2 lines
Cheers,
Stephen Rothwell

---end quoted text---

#2 lore raw

Em Fri, 23 Feb 2024 07:35:54 +0100
Christoph Hellwig <[email protected]> escreveu:

Quoted 11 lines · Stephen Rothwell
Quoted 7 lines

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

#3 lore raw
Quoted 7 lines · Mauro Carvalho Chehab

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..

#4 lore raw

Hi,

Quoted 7 lines · Christoph Hellwig
Quoted 6 lines · Mauro Carvalho Chehab

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``
Quoted 6 lines
Quoted 1 line

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).

scripts/kernel-doc +1 -1
index 136104804375..bdd6f3b489cc 100755
@@ -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+)';
Signature · 2 lines
And you would be able to write the kernel-doc comment in question
as follows:
mm/shmem.c +2 -2
index 750ab1dcae27..0aad0d9a621b 100644
@@ -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.
  *
Signature · 3 lines
How does this approach sound to you? 

        Thanks, Akira
#5 lore raw
Quoted 1 line · Akira Yokosawa

How about teaching kernel-doc unary "*" on param?

That would be great!

Quoted 6 lines

Substitution would look like:

   (kernel-doc)       (RST)
   *@param     ->  ***param**
Quoted 6 lines

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: