linux-kernel - [RFC PATCH] scripts: kernel-doc: allow printing the documented symbols

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [day] [month] [year] [list]

Date:   Fri,  9 Oct 2020 14:55:18 +0200
From:   Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To:     "Jonathan Corbet" <corbet@....net>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>
Cc:     Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
        linux-kernel@...r.kernel.org
Subject: [RFC PATCH] scripts: kernel-doc: allow printing the documented symbols

It is useful to know what symbols are documented, as
scripts could use this in order to check for documentation
issues. This comes almost for free from kernel-doc parsing.

So, add support for it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
---

While checking what's documented on some media files, I found
the lack of a feature that would report it on an easy way.

Well, it turns that it is very easy to make kernel-doc report it.
With that, it is easy to check, for example, what are the external
symbols that are documented with:

$ ./scripts/kernel-doc --export --symbols drivers/media/dvb-core/dvb_ca_en50221.c
dvb_ca_en50221_camchange_irq()
dvb_ca_en50221_camready_irq()
dvb_ca_en50221_frda_irq()
dvb_ca_en50221_init()
dvb_ca_en50221_release()

And the internal ones with:

$ ./scripts/kernel-doc --internal --symbols drivers/media/dvb-core/dvb_ca_en50221.c
findstr()
dvb_ca_en50221_wait_if_status()
dvb_ca_en50221_link_init()
dvb_ca_en50221_read_tuple()
dvb_ca_en50221_parse_attributes()
dvb_ca_en50221_set_configoption()
dvb_ca_en50221_read_data()
dvb_ca_en50221_write_data()
dvb_ca_en50221_slot_shutdown()
dvb_ca_en50221_thread_wakeup()
dvb_ca_en50221_thread_update_delay()
dvb_ca_en50221_poll_cam_gone()
dvb_ca_en50221_thread_state_machine()
dvb_ca_en50221_io_do_ioctl()
dvb_ca_en50221_io_ioctl()
dvb_ca_en50221_io_write()
dvb_ca_en50221_io_read()
dvb_ca_en50221_io_open()
dvb_ca_en50221_io_release()
dvb_ca_en50221_io_poll()


 scripts/kernel-doc | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 297312824d26..9168a783efd1 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -55,6 +55,7 @@ Output format selection (mutually exclusive):
   -man			Output troff manual page format. This is the default.
   -rst			Output reStructuredText format.
   -none			Do not output documentation, only warnings.
+  -symbols		Output just the documented symbol names.
 
 Output format selection modifier (affects only ReST output):
 
@@ -434,6 +435,8 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
 	$blankline = $blankline_rst;
     } elsif ($cmd eq "none") {
 	$output_mode = "none";
+    } elsif ($cmd eq "symbols") {
+	$output_mode = "symbols";
     } elsif ($cmd eq "module") { # not needed for XML, inherits from calling document
 	$modulename = shift @ARGV;
     } elsif ($cmd eq "function") { # to only output specific functions
@@ -1139,6 +1142,35 @@ sub output_struct_none(%) {
 sub output_blockhead_none(%) {
 }
 
+## symbols mode output functions
+
+sub output_function_symbols(%) {
+        my %args = %{$_[0]};
+
+	print "$args{'function'}()\n";
+}
+
+sub output_enum_symbols(%) {
+        my %args = %{$_[0]};
+
+	print "enum $args{'enum'}\n";
+}
+
+sub output_typedef_symbols(%) {
+        my %args = %{$_[0]};
+
+	print "typedef $args{'typedef'}\n";
+}
+
+sub output_struct_symbols(%) {
+        my %args = %{$_[0]};
+
+	print "struct $args{'struct'}\n";
+}
+
+sub output_blockhead_symbols(%) {
+}
+
 ##
 # generic output function for all types (function, struct/union, typedef, enum);
 # calls the generated, variable output_ function name based on
-- 
2.26.2