[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH v2 25/32] scripts: kernel-doc: try to use c:function if possible
From: |
Paolo Bonzini |
Subject: |
[PATCH v2 25/32] scripts: kernel-doc: try to use c:function if possible |
Date: |
Tue, 1 Dec 2020 05:34:55 -0500 |
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
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>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201117165312.118257-25-pbonzini@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
scripts/kernel-doc | 23 ++++++++++++++---------
1 file changed, 14 insertions(+), 9 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 98752164eb..2d56c46933 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'});
--
2.26.2
- [PATCH v2 14/32] scripts: kernel-doc: add support for typedef enum, (continued)
- [PATCH v2 14/32] scripts: kernel-doc: add support for typedef enum, Paolo Bonzini, 2020/12/01
- [PATCH v2 07/32] scripts: kernel-doc: accept blank lines on parameter description, Paolo Bonzini, 2020/12/01
- [PATCH v2 15/32] Revert "scripts/kerneldoc: For Sphinx 3 use c:macro for macros with arguments", Paolo Bonzini, 2020/12/01
- [PATCH v2 10/32] scripts/kernel-doc: handle function pointer prototypes, Paolo Bonzini, 2020/12/01
- [PATCH v2 11/32] scripts/kernel-doc: optionally treat warnings as errors, Paolo Bonzini, 2020/12/01
- [PATCH v2 02/32] kernel-doc: fix processing nested structs with attributes, Paolo Bonzini, 2020/12/01
- [PATCH v2 16/32] Revert "kernel-doc: Use c:struct for Sphinx 3.0 and later", Paolo Bonzini, 2020/12/01
- [PATCH v2 26/32] Revert "kernel-doc: Handle function typedefs without asterisks", Paolo Bonzini, 2020/12/01
- [PATCH v2 19/32] scripts: kernel-doc: fix troubles with line counts, Paolo Bonzini, 2020/12/01
- [PATCH v2 20/32] scripts: kernel-doc: reimplement -nofunction argument, Paolo Bonzini, 2020/12/01
- [PATCH v2 25/32] scripts: kernel-doc: try to use c:function if possible,
Paolo Bonzini <=
- [PATCH v2 12/32] kernel-doc: include line numbers for function prototypes, Paolo Bonzini, 2020/12/01
- [PATCH v2 29/32] scripts: kernel-doc: split typedef complex regex, Paolo Bonzini, 2020/12/01
- [PATCH v2 13/32] kernel-doc: add support for ____cacheline_aligned attribute, Paolo Bonzini, 2020/12/01
- [PATCH v2 24/32] scripts: kernel-doc: fix line number handling, Paolo Bonzini, 2020/12/01
- [PATCH v2 23/32] scripts: kernel-doc: allow passing desired Sphinx C domain dialect, Paolo Bonzini, 2020/12/01
- [PATCH v2 27/32] Revert "kernel-doc: Handle function typedefs that return pointers", Paolo Bonzini, 2020/12/01
- [PATCH v2 22/32] scripts: kernel-doc: don't mangle with parameter list, Paolo Bonzini, 2020/12/01
- [PATCH v2 21/32] scripts: kernel-doc: fix typedef identification, Paolo Bonzini, 2020/12/01
- [PATCH v2 30/32] scripts: kernel-doc: use :c:union when needed, Paolo Bonzini, 2020/12/01
- [PATCH v2 32/32] scripts: kernel-doc: remove unnecesssary change wrt Linux, Paolo Bonzini, 2020/12/01