While not all EXPORT_SYMBOL*() symbols should be documented,
it seems useful to have a tool which would help to check what
symbols aren't documented.
This is a first step on this direction. The tool has some
limitations. Yet, it could be useful for maintainers to check
about missing documents on their subsystems.
Suggested-by: Matthew Wilcox
Signed-off-by: Mauro Carvalho Chehab
---
scripts/check_docs_external_symbols | 267
1 file changed, 267 insertions(+)
create mode 100755 scripts/check_docs_external_symbols
diff --git a/scripts/check_docs_external_symbols
b/scripts/check_docs_external_symbols
new file mode 100755
index ..cfa49015ded3
--- /dev/null
+++ b/scripts/check_docs_external_symbols
@@ -0,0 +1,267 @@
+#!/usr/bin/perl
+# SPDX-License-Identifier: GPL-2.0
+
+#
+# Copyright (c) 2020, Huawei Tech. Co., Ltd.
+# Author: Mauro Carvalho Chehab
+
+use warnings;
+use strict;
+use File::Find;
+use Cwd 'abs_path';
+
+use Data::Dumper;
+
+sub check_kerneldoc_symbols() {
+ my $file = shift;
+ my $docfile = shift;
+ my $exp = shift;
+ my $h = shift;
+ my @exports = @{$exp};
+ my %hash = %{$h};
+ my $is_kerneldoc = 0;
+ my $kerneldoc;
+ my $type;
+ my ($indent, $tag_indent);
+ my (@yes_symbols, @no_symbols);
+
+ $file = abs_path($file);
+
+ open IN, $docfile or return 0;
+ while () {
+ while (s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
+ if (/^(\s*)\.\.\s+kernel-doc\:\:\s*(\S+)/) {
+ $indent = $1;
+ $kerneldoc = abs_path($2);
+ $is_kerneldoc = 1;
+ @yes_symbols = @exports;
+ @no_symbols = ();
+ $tag_indent = "";
+ next;
+ }
+
+ next if (!$is_kerneldoc);
+
+ if ($tag_indent ne "" && /^($tag_indent)\s+(.*)/) {
+ my @sym = split /\s+/, $2;
+ if ($type eq "identifiers") {
+ push @yes_symbols, @sym;
+ } else {
+ push @no_symbols, @sym;
+ }
+
+ next;
+ }
+
+ if (/^($indent)\S/) {
+ $is_kerneldoc = 0;
+
+ if ($kerneldoc eq $file) {
+ $hash{$_}++ for (@yes_symbols);
+ $hash{$_}-- for (@no_symbols);
+ }
+
+ next;
+ }
+
+ next if ($kerneldoc ne $file);
+
+ # Check for kernel-doc variants
+
+ if (m/:internal:/) {
+ @yes_symbols = ();
+ next;
+ }
+ if (m/:export:/) {
+ # Nothing to do here, as exports are covered
+ next;
+ }
+
+ # Those are more painful to handle
+ if (m/^(\s+):identifiers:\s*(.*)/ ||
m/^(\s+):functions:\s*(.*)/) {
+ $tag_indent = $1;
+ $type = "identifiers";
+ @yes_symbols = split /\s+/, $2;
+
+ next;
+ }
+ if (m/^(\s+):no-identifiers:\s*(.*)/) {
+ $type = "no-identifiers";
+ $tag_indent = $1;
+ @no_symbols = split /\s+/, $2;
+
+ next;
+ }
+ }
+
+ if ($is_kerneldoc) {
+ if ($kerneldoc eq $file) {
+ $hash{$_}++ for (@yes_symbols);
+ $hash{$_}-- for (@no_symbols);
+ }
+ }
+
+
+ close IN;
+
+ return %hash;
+}
+
+sub check_file($) {
+ my $file = shift;
+ my (@files, @exports, @doc, @doc_refs, %file_exports, %hash);
+ my $content = "\n";
+
+ $file =~ s/\s+$//;
+
+ return 0 if (!($file =~ /\.[ch]$/));
+
+ my $dir = $file;
+ $dir =~ s,[^\/]+$,,;
+
+ open IN, $file or return 0;
+ while () {
+ push @exports, $1 if (m/^EXPORT_SYMBOL.*\(\s*(\S+)\s*\)/);
+
+ if (m/^\s*#\s*include\s+[\<](\S+)[\>]/) {
+ if (-e "include/uapi/$1") {
+ push @files, "include/uapi/$1";
+ } elsif (-e "include/$1") {
+ push @files, "include/$1";
+ } else {
+ my @inc = split /\s+/,qx(git ls-files|grep $1);
+ push @files, @inc;
+ }
+ }
+ if (m/^\s*#\s*include\s+[\"](\S+)[\"]/) {
+ if (-e "$dir/$1") {
+ push @files, "$dir/$1";
+ }
