[PATCH v5 50/52] scripts: kernel-doc: try to use c:function if possible

From: Mauro Carvalho Chehab
Date: Tue Oct 06 2020 - 10:05:26 EST


There are a few namespace clashes by using c:macro everywhere:

basically, when using it, we can't have something like:

.. c:struct:: pwm_capture

.. c:macro:: pwm_capture

So, we need to use, instead:

.. c:function:: int pwm_capture (struct pwm_device * pwm, struct pwm_capture * result, unsigned long timeout)

for the function declaration.

The kernel-doc change was proposed by Jakob Lykke Andersen here:

https://github.com/jakobandersen/linux_docs/commit/6fd2076ec001cca7466857493cd678df4dfe4a65

Although I did a different implementation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
---
scripts/kernel-doc | 23 ++++++++++++++---------
1 file changed, 14 insertions(+), 9 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9881f08cf75c..a3453de4495c 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -913,6 +913,7 @@ sub output_function_rst(%) {
my ($parameter, $section);
my $oldprefix = $lineprefix;
my $start = "";
+ my $is_macro = 0;

if ($sphinx_major < 3) {
if ($args{'typedef'}) {
@@ -922,11 +923,17 @@ sub output_function_rst(%) {
$lineprefix = "";
output_highlight_rst($args{'purpose'});
$start = "\n\n**Syntax**\n\n ``";
+ $is_macro = 1;
} else {
print ".. c:function:: ";
}
} else {
- print ".. c:macro:: ". $args{'function'} . "\n\n";
+ if ($args{'typedef'} || $args{'functiontype'} eq "") {
+ $is_macro = 1;
+ print ".. c:macro:: ". $args{'function'} . "\n\n";
+ } else {
+ print ".. c:function:: ";
+ }

if ($args{'typedef'}) {
print_lineno($declaration_start_line);
@@ -935,7 +942,7 @@ sub output_function_rst(%) {
output_highlight_rst($args{'purpose'});
$start = "\n\n**Syntax**\n\n ``";
} else {
- print "``";
+ print "``" if ($is_macro);
}
}
if ($args{'functiontype'} ne "") {
@@ -960,14 +967,12 @@ sub output_function_rst(%) {
print $type;
}
}
- if ($args{'typedef'}) {
- print ");``\n\n";
+ if ($is_macro) {
+ print ")``\n\n";
} else {
- if ($sphinx_major < 3) {
- print ")\n\n";
- } else {
- print ")``\n";
- }
+ print ")\n\n";
+ }
+ if (!$args{'typedef'}) {
print_lineno($declaration_start_line);
$lineprefix = " ";
output_highlight_rst($args{'purpose'});
--
2.26.2