Skip to contentSkip to conversation

kernel-doc: Add unary operator * to $type_param_ref

PATCH In review Akira Yokosawa 3 participants 4 messages Feb 27, 2024 – Feb 28, 2024

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

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

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.

---
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(-)
scripts/kernel-doc +1 -1
index e8aefd258a29..d2f3fa3505c6 100755
@@ -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+)';

base-commit: 4b2f459d86252619448455013f581836c8b1b7da

Signature · 1 line
2.34.1
#1 lore raw

PATCH 2/2 mm/shmem.c: Use new form of *@param in kernel-doc

Use the form of *@param which kernel-doc recognizes now. This resolves the warnings from "make htmldocs" as reported in [1].

---
 mm/shmem.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
mm/shmem.c +2 -2
index fb76da93d369..cf3689926418 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 · 1 line
2.34.1
Acked-by on v1 1/2
#2 lore raw
In reply to Akira Yokosawa
Quoted 25 lines · Akira Yokosawa

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.

Quoted 6 lines

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

Thanks,

jon

#3 lore raw
Quoted 34 lines · Jonathan Corbet
Quoted 25 lines · Akira Yokosawa

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.

Quoted 6 lines

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

Quoted 6 lines

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:

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

--D

Quoted 4 lines

Thanks,

jon