diff options
author | Mauro Carvalho Chehab <mchehab+huawei@kernel.org> | 2020-09-30 09:47:01 +0200 |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab+huawei@kernel.org> | 2020-10-15 07:49:37 +0200 |
commit | 6e9e415854c15dbf920481eb1d245988e405bbc0 (patch) | |
tree | 67ca21cd669c9753bc5ac73aafe5bbcd2a6e1196 | |
parent | 5ef09c96d48b41a55121df1b57404f68d7e4e5f1 (diff) | |
download | linux-6e9e415854c15dbf920481eb1d245988e405bbc0.tar.gz linux-6e9e415854c15dbf920481eb1d245988e405bbc0.tar.bz2 linux-6e9e415854c15dbf920481eb1d245988e405bbc0.zip |
scripts: kernel-doc: try to use c:function if possible
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@kernel.org>
-rwxr-xr-x | scripts/kernel-doc | 23 |
1 files changed, 14 insertions, 9 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 9496abba9538..c8f6b11d5da1 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -917,6 +917,7 @@ sub output_function_rst(%) { my ($parameter, $section); my $oldprefix = $lineprefix; my $start = ""; + my $is_macro = 0; if ($sphinx_major < 3) { if ($args{'typedef'}) { @@ -926,11 +927,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); @@ -939,7 +946,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 "") { @@ -964,14 +971,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'}); |