From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Linux Doc Mailing List <linux-doc@vger.kernel.org>,
Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
linux-kernel@vger.kernel.org
Subject: [PATCH v4 07/52] scripts: kernel-doc: reimplement -nofunction argument
Date: Wed, 30 Sep 2020 15:24:30 +0200 [thread overview]
Message-ID: <38b2fc38452e47d87168800f174a150ffab64740.1601467849.git.mchehab+huawei@kernel.org> (raw)
In-Reply-To: <cover.1601467849.git.mchehab+huawei@kernel.org>
Right now, the build system doesn't use -nofunction, as
it is pretty much useless, because it doesn't consider
the other output modes (extern, internal), working only
with all.
Also, it is limited to exclude functions.
Re-implement it in order to allow excluding any symbols from
the document output, no matter what mode is used.
The parameter was also renamed to "-nosymbol", as it express
better its meaning.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/kernel-doc | 44 +++++++++++++++++++++-----------------------
1 file changed, 21 insertions(+), 23 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 07b1073b0bc0..6588a0d27fe4 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -66,9 +66,8 @@ Output selection (mutually exclusive):
-function NAME Only output documentation for the given function(s)
or DOC: section title(s). All other functions and DOC:
sections are ignored. May be specified multiple times.
- -nofunction NAME Do NOT output documentation for the given function(s);
- only output documentation for the other functions and
- DOC: sections. May be specified multiple times.
+ -nosymbol NAME Exclude the specified symbols from the output
+ documentation. May be specified multiple times.
Output selection modifiers:
-no-doc-sections Do not output DOC: sections.
@@ -288,9 +287,8 @@ my $modulename = "Kernel API";
use constant {
OUTPUT_ALL => 0, # output all symbols and doc sections
OUTPUT_INCLUDE => 1, # output only specified symbols
- OUTPUT_EXCLUDE => 2, # output everything except specified symbols
- OUTPUT_EXPORTED => 3, # output exported symbols
- OUTPUT_INTERNAL => 4, # output non-exported symbols
+ OUTPUT_EXPORTED => 2, # output exported symbols
+ OUTPUT_INTERNAL => 3, # output non-exported symbols
};
my $output_selection = OUTPUT_ALL;
my $show_not_found = 0; # No longer used
@@ -315,6 +313,7 @@ my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
# CAVEAT EMPTOR! Some of the others I localised may not want to be, which
# could cause "use of undefined value" or other bugs.
my ($function, %function_table, %parametertypes, $declaration_purpose);
+my %nosymbol_table = ();
my $declaration_start_line;
my ($type, $declaration_name, $return_type);
my ($newsection, $newcontents, $prototype, $brcount, %source_map);
@@ -434,10 +433,9 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
$output_selection = OUTPUT_INCLUDE;
$function = shift @ARGV;
$function_table{$function} = 1;
- } elsif ($cmd eq "nofunction") { # output all except specific functions
- $output_selection = OUTPUT_EXCLUDE;
- $function = shift @ARGV;
- $function_table{$function} = 1;
+ } elsif ($cmd eq "nosymbol") { # Exclude specific symbols
+ my $symbol = shift @ARGV;
+ $nosymbol_table{$symbol} = 1;
} elsif ($cmd eq "export") { # only exported symbols
$output_selection = OUTPUT_EXPORTED;
%function_table = ();
@@ -570,11 +568,11 @@ sub dump_doc_section {
return;
}
+ return if (defined($nosymbol_table{$name}));
+
if (($output_selection == OUTPUT_ALL) ||
- ($output_selection == OUTPUT_INCLUDE &&
- defined($function_table{$name})) ||
- ($output_selection == OUTPUT_EXCLUDE &&
- !defined($function_table{$name})))
+ (($output_selection == OUTPUT_INCLUDE) &&
+ defined($function_table{$name})))
{
dump_section($file, $name, $contents);
output_blockhead({'sectionlist' => \@sectionlist,
@@ -800,6 +798,8 @@ sub output_blockhead_rst(%) {
my ($parameter, $section);
foreach $section (@{$args{'sectionlist'}}) {
+ next if (defined($nosymbol_table{$section}));
+
if ($output_selection != OUTPUT_INCLUDE) {
print "**$section**\n\n";
}
@@ -1115,12 +1115,14 @@ sub output_declaration {
my $name = shift;
my $functype = shift;
my $func = "output_${functype}_$output_mode";
+
+ return if (defined($nosymbol_table{$name}));
+
if (($output_selection == OUTPUT_ALL) ||
(($output_selection == OUTPUT_INCLUDE ||
$output_selection == OUTPUT_EXPORTED) &&
defined($function_table{$name})) ||
- (($output_selection == OUTPUT_EXCLUDE ||
- $output_selection == OUTPUT_INTERNAL) &&
+ ($output_selection == OUTPUT_INTERNAL &&
!($functype eq "function" && defined($function_table{$name}))))
{
&$func(@_);
@@ -1301,6 +1303,8 @@ sub show_warnings($$) {
my $functype = shift;
my $name = shift;
+ return 0 if (defined($nosymbol_table{$name}));
+
return 1 if ($output_selection == OUTPUT_ALL);
if ($output_selection == OUTPUT_EXPORTED) {
@@ -1324,13 +1328,6 @@ sub show_warnings($$) {
return 0;
}
}
- if ($output_selection == OUTPUT_EXCLUDE) {
- if (!defined($function_table{$name})) {
- return 1;
- } else {
- return 0;
- }
- }
die("Please add the new output type at show_warnings()");
}
@@ -1945,6 +1942,7 @@ sub process_export_file($) {
while (<IN>) {
if (/$export_symbol/) {
+ next if (defined($nosymbol_table{$2}));
$function_table{$2} = 1;
}
}
--
2.26.2
next prev parent reply other threads:[~2020-09-30 13:28 UTC|newest]
Thread overview: 89+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-09-30 13:24 [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 01/52] docs: cdomain.py: add support for a new Sphinx 3.1+ tag Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 02/52] docs: cdomain.py: extend it to handle new Sphinx 3.x tags Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 03/52] docs: conf.py: disable automarkup for Sphinx 3.x Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 04/52] scripts: kernel-doc: make it more compatible with " Mauro Carvalho Chehab
2020-10-01 21:41 ` Jonathan Corbet
2020-10-01 23:02 ` Jonathan Corbet
2020-10-02 6:22 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 05/52] scripts: kernel-doc: use a less pedantic markup for funcs on " Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 06/52] scripts: kernel-doc: fix troubles with line counts Mauro Carvalho Chehab
2020-09-30 13:24 ` Mauro Carvalho Chehab [this message]
2020-09-30 13:24 ` [PATCH v4 08/52] scripts: kernel-doc: fix typedef identification Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 09/52] scripts: kernel-doc: don't mangle with parameter list Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 10/52] docs: kerneldoc.py: append the name of the parsed doc file Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 11/52] docs: kerneldoc.py: add support for kerneldoc -nosymbol Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 12/52] media: docs: make CEC documents compatible with Sphinx 3.1+ Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 13/52] media: docs: make V4L documents more " Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 14/52] media: docs: make DVB " Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 15/52] media: docs: make MC " Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 16/52] media: docs: make RC " Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 17/52] media: cec-core.rst: don't use c:type for structs Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 18/52] math64.h: kernel-docs: Convert some markups into normal comments Mauro Carvalho Chehab
2020-09-30 13:46 ` Vincenzo Frascino
2020-09-30 13:24 ` [PATCH v4 19/52] memblock: get rid of a :c:type leftover Mauro Carvalho Chehab
2020-09-30 14:23 ` Mike Rapoport
2020-09-30 15:13 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 20/52] drm: drm_dsc.h: fix a kernel-doc markup Mauro Carvalho Chehab
2020-09-30 14:42 ` Daniel Vetter
2020-09-30 13:24 ` [PATCH v4 21/52] docs: remove some replace macros like |struct foo| Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 22/52] docs: get rid of :c:type explicit declarations for structs Mauro Carvalho Chehab
2020-09-30 14:26 ` Mike Rapoport
2020-09-30 15:01 ` Takashi Iwai
2020-09-30 16:50 ` André Almeida
2020-09-30 13:24 ` [PATCH v4 23/52] docs: trace-uses.rst: remove bogus c-domain tags Mauro Carvalho Chehab
2020-09-30 16:35 ` Steven Rostedt
2020-10-01 6:06 ` Kamalesh Babulal
2020-10-01 6:41 ` Mauro Carvalho Chehab
2020-10-01 8:27 ` Kamalesh Babulal
2020-09-30 13:24 ` [PATCH v4 24/52] docs: it_IT: fix namespace collisions at locking.rst Mauro Carvalho Chehab
2020-10-01 12:04 ` Federico Vaga
2020-09-30 13:24 ` [PATCH v4 25/52] docs: net: ieee802154.rst: fix C expressions Mauro Carvalho Chehab
2020-09-30 21:23 ` David Miller
2020-09-30 13:24 ` [PATCH v4 26/52] docs: genericirq.rst: don't document chip.c functions twice Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 27/52] docs: kernel-api.rst: drop kernel/irq/manage.c kernel-doc tag Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 28/52] docs: remove sound API duplication Mauro Carvalho Chehab
2020-09-30 14:57 ` Takashi Iwai
2020-09-30 13:24 ` [PATCH v4 29/52] docs: basics.rst: move kernel-doc workqueue markups to workqueue.rst Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 30/52] docs: scsi: target.rst: remove iSCSI transport class kernel-doc markup Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 31/52] docs: device_link.rst: remove duplicated kernel-doc include Mauro Carvalho Chehab
2020-09-30 21:03 ` Saravana Kannan
2020-09-30 13:24 ` [PATCH v4 32/52] docs: basics.rst: get rid of rcu kernel-doc macros Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 33/52] docs: net: statistics.rst: remove a duplicated kernel-doc Mauro Carvalho Chehab
2020-09-30 21:23 ` David Miller
2020-09-30 13:24 ` [PATCH v4 34/52] docs: pstore-blk.rst: fix kernel-doc tags Mauro Carvalho Chehab
2020-09-30 23:23 ` Kees Cook
2020-09-30 13:24 ` [PATCH v4 35/52] docs: fs: fscrypt.rst: get rid of :c:type: tags Mauro Carvalho Chehab
2020-09-30 16:21 ` Eric Biggers
2020-09-30 16:53 ` Mauro Carvalho Chehab
2020-09-30 17:06 ` Eric Biggers
2020-10-05 12:06 ` Mauro Carvalho Chehab
2020-10-05 19:08 ` Eric Biggers
2020-10-06 8:23 ` Mauro Carvalho Chehab
2020-09-30 13:24 ` [PATCH v4 36/52] docs: devices.rst: get rid of :c:type macros Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 37/52] docs: sound: writing-an-alsa-driver.rst: get rid of :c:type Mauro Carvalho Chehab
2020-09-30 14:59 ` Takashi Iwai
2020-09-30 13:25 ` [PATCH v4 38/52] docs: block: typec_bus.rst: " Mauro Carvalho Chehab
2020-09-30 16:48 ` André Almeida
2020-09-30 13:25 ` [PATCH v4 39/52] docs: writing-an-alsa-driver.rst: fix some bad c:func: markups Mauro Carvalho Chehab
2020-09-30 14:58 ` Takashi Iwai
2020-09-30 13:25 ` [PATCH v4 40/52] docs: fpga: replace :c:member: macros Mauro Carvalho Chehab
2020-09-30 23:46 ` Moritz Fischer
2020-09-30 13:25 ` [PATCH v4 41/52] docs: kgdb.rst: fix :c:type: usages Mauro Carvalho Chehab
2020-10-01 11:29 ` Daniel Thompson
2020-09-30 13:25 ` [PATCH v4 42/52] docs: libata.rst: fix a wrong usage of :c:type: tag Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 43/52] docs: infrastructure.rst: don't include firmware kernel-doc Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 44/52] docs: gpu: i915.rst: Fix several C duplication warnings Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 45/52] docs: devices.rst: fix a C reference markup Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 46/52] docs: it_IT: hacking.rst: fix a typo on a markup Mauro Carvalho Chehab
2020-10-01 12:05 ` Federico Vaga
2020-09-30 13:25 ` [PATCH v4 47/52] docs: mei.rst: fix a C expression markup Mauro Carvalho Chehab
2020-09-30 20:30 ` Winkler, Tomas
2020-09-30 13:25 ` [PATCH v4 48/52] docs: basics.rst: avoid duplicated C function declaration Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 49/52] workqueue: fix a kernel-doc warning Mauro Carvalho Chehab
2020-09-30 15:57 ` Tejun Heo
2020-09-30 13:25 ` [PATCH v4 50/52] scripts: kernel-doc: try to use c:function if possible Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 51/52] docs: conf.py: fix c:function support with Sphinx 3.x Mauro Carvalho Chehab
2020-09-30 13:25 ` [PATCH v4 52/52] docs: conf.py: change the Sphinx 3.x+ text Mauro Carvalho Chehab
2020-10-01 21:48 ` [PATCH v4 00/52] Fix html build with Sphinx 3.1 and above Jonathan Corbet
2020-10-02 6:52 ` Mauro Carvalho Chehab
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=38b2fc38452e47d87168800f174a150ffab64740.1601467849.git.mchehab+huawei@kernel.org \
--to=mchehab+huawei@kernel.org \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).