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.
Thanks, Akira
---
scripts/kernel-doc | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e8aefd258a29..d2f3fa3505c6 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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
--
2.34.1
