[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 17/29] scripts: kernel-doc: use a less pedantic markup for funcs
From: |
Paolo Bonzini |
Subject: |
[PATCH 17/29] scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx 3.x |
Date: |
Tue, 17 Nov 2020 17:53:00 +0100 |
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Unfortunately, Sphinx 3.x parser for c functions is too pedantic:
https://github.com/sphinx-doc/sphinx/issues/8241
While it could be relaxed with some configurations, there are
several corner cases that it would make it hard to maintain,
and will require teaching conf.py about several macros.
So, let's instead use the :c:macro notation. This will
produce an output that it is not as nice as currently, but it
should still be acceptable, and will provide cross-references,
removing thousands of warnings when building with newer
versions of Sphinx.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
scripts/kernel-doc | 34 ++++++++++++++++++++++++----------
1 file changed, 24 insertions(+), 10 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 771367a6ab..75ddd3b5e6 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -886,19 +886,29 @@ sub output_function_rst(%) {
my $oldprefix = $lineprefix;
my $start = "";
- if ($args{'typedef'}) {
- if ($sphinx_major < 3) {
+ if ($sphinx_major < 3) {
+ if ($args{'typedef'}) {
print ".. c:type:: ". $args{'function'} . "\n\n";
+ print_lineno($declaration_start_line);
+ print " **Typedef**: ";
+ $lineprefix = "";
+ output_highlight_rst($args{'purpose'});
+ $start = "\n\n**Syntax**\n\n ``";
} else {
- print ".. c:function:: ". $args{'function'} . "\n\n";
+ print ".. c:function:: ";
}
- print_lineno($declaration_start_line);
- print " **Typedef**: ";
- $lineprefix = "";
- output_highlight_rst($args{'purpose'});
- $start = "\n\n**Syntax**\n\n ``";
} else {
- print ".. c:function:: ";
+ print ".. c:macro:: ". $args{'function'} . "\n\n";
+
+ if ($args{'typedef'}) {
+ print_lineno($declaration_start_line);
+ print " **Typedef**: ";
+ $lineprefix = "";
+ output_highlight_rst($args{'purpose'});
+ $start = "\n\n**Syntax**\n\n ``";
+ } else {
+ print "``";
+ }
}
if ($args{'functiontype'} ne "") {
$start .= $args{'functiontype'} . " " . $args{'function'} . " (";
@@ -925,7 +935,11 @@ sub output_function_rst(%) {
if ($args{'typedef'}) {
print ");``\n\n";
} else {
- print ")\n\n";
+ if ($sphinx_major < 3) {
+ print ")\n\n";
+ } else {
+ print ")``\n";
+ }
print_lineno($declaration_start_line);
$lineprefix = " ";
output_highlight_rst($args{'purpose'});
--
2.28.0
- [PATCH 08/29] scripts/kernel-doc: parse __ETHTOOL_DECLARE_LINK_MODE_MASK, (continued)
- [PATCH 08/29] scripts/kernel-doc: parse __ETHTOOL_DECLARE_LINK_MODE_MASK, Paolo Bonzini, 2020/11/17
- [PATCH 09/29] scripts/kernel-doc: handle function pointer prototypes, Paolo Bonzini, 2020/11/17
- [PATCH 10/29] scripts/kernel-doc: optionally treat warnings as errors, Paolo Bonzini, 2020/11/17
- [PATCH 12/29] kernel-doc: add support for ____cacheline_aligned attribute, Paolo Bonzini, 2020/11/17
- [PATCH 11/29] kernel-doc: include line numbers for function prototypes, Paolo Bonzini, 2020/11/17
- [PATCH 13/29] scripts: kernel-doc: add support for typedef enum, Paolo Bonzini, 2020/11/17
- [PATCH 14/29] Revert "scripts/kerneldoc: For Sphinx 3 use c:macro for macros with arguments", Paolo Bonzini, 2020/11/17
- [PATCH 15/29] Revert "kernel-doc: Use c:struct for Sphinx 3.0 and later", Paolo Bonzini, 2020/11/17
- [PATCH 16/29] scripts: kernel-doc: make it more compatible with Sphinx 3.x, Paolo Bonzini, 2020/11/17
- [PATCH 18/29] scripts: kernel-doc: fix troubles with line counts, Paolo Bonzini, 2020/11/17
- [PATCH 17/29] scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx 3.x,
Paolo Bonzini <=
- [PATCH 19/29] scripts: kernel-doc: reimplement -nofunction argument, Paolo Bonzini, 2020/11/17
- [PATCH 20/29] scripts: kernel-doc: fix typedef identification, Paolo Bonzini, 2020/11/17
- [PATCH 25/29] Revert "kernel-doc: Handle function typedefs without asterisks", Paolo Bonzini, 2020/11/17
- [PATCH 21/29] scripts: kernel-doc: don't mangle with parameter list, Paolo Bonzini, 2020/11/17
- [PATCH 22/29] scripts: kernel-doc: allow passing desired Sphinx C domain dialect, Paolo Bonzini, 2020/11/17
- [PATCH 23/29] scripts: kernel-doc: fix line number handling, Paolo Bonzini, 2020/11/17
- [PATCH 24/29] scripts: kernel-doc: try to use c:function if possible, Paolo Bonzini, 2020/11/17
- [PATCH 26/29] Revert "kernel-doc: Handle function typedefs that return pointers", Paolo Bonzini, 2020/11/17
- [PATCH 27/29] scripts: kernel-doc: fix typedef parsing, Paolo Bonzini, 2020/11/17
- [PATCH 29/29] scripts: kernel-doc: use :c:union when needed, Paolo Bonzini, 2020/11/17