Skip to content

Commit

Permalink
kernel-doc: Add unary operator * to $type_param_ref
Browse files Browse the repository at this point in the history
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@canb.auug.org.au>
Link: [1] https://lore.kernel.org/r/20240223153636.41358be5@canb.auug.org.au/
Acked-by: Christoph Hellwig <hch@lst.de>
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Chandan Babu R <chandanbabu@kernel.org>
  • Loading branch information
Akira Yokosawa authored and Chandan Babu R committed Feb 29, 2024
1 parent b8c0d6f commit 69fc23e
Showing 1 changed file with 1 addition and 1 deletion.
2 changes: 1 addition & 1 deletion scripts/kernel-doc
Original file line number Diff line number Diff line change
Expand Up @@ -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+)';
Expand Down

0 comments on commit 69fc23e

Please sign in to comment.