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 <willy@xxxxxxxxxxxxx>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
---
scripts/check_docs_external_symbols | 127 ++++++++++++++++++++++++++++
1 file changed, 127 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 000000000000..cc12562e6cd6
--- /dev/null
+++ b/scripts/check_docs_external_symbols
@@ -0,0 +1,127 @@
+#!/usr/bin/perl
+# SPDX-License-Identifier: GPL-2.0
+
+#
+# Copyright (c) 2020, Huawei Tech. Co., Ltd.
+# Author: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx
+#
+# This script helps to check if exported functions are documented at either
+# a file, on at the included headers.
+#
+# The script is not perfect and may produce some false negatives, as
+# currently it doesn't handle Makefile "-I" directives that might be inside
+# a Kernel directory.
+#
+# So, use it with caution.
+#
+# Usage:
+# scripts/check_external docs
+# or:
+# scripts/check_external docs <files and/or directories>
+
+use warnings;
+use strict;
+use File::Find;
+
+sub check_file($) {
+ my $file = shift;
+ my (@files, @exports, @doc, @doc_refs);
+ my $content = "\n";
+
+ return 0 if (!($file =~ /\.[ch]$/));
+
+ my $dir = $file;
+ $dir =~ s,[^\/]+$,,;
+
+ open IN, $file or return 0;
+ while (<IN>) {
+ push @exports, $1 if (m/^EXPORT_SYMBOL.*\(\s*(\S+)\s*\)/);
+
+ if (m/^\s*#\s*include\s+[\<](\S+)[\>]/) {
+ if (-e "include/$1") {
+ push @files, "include/$1";
+ } else {
+ # Currently, can't check if include is elsewhere
+ return 0;
+ }
+ }
+ if (m/^\s*#\s*include\s+[\"](\S+)[\"]/) {
+ if (-e "$dir/$1") {
+ push @files, "$dir/$1";
+ } else {
+ # Currently, can't check if include is elsewhere
+ return 0;
+ }
+ }
+ $content .= $_;
+ }
+ close IN;
+
+ return 0 if ($content eq "\n");
+
+
+ push @files, $file;
+ for (my $i = 0; $i < scalar(@files); $i++) {
+ $doc_refs[$i] = 0;
+ $doc[$i] = qx(./scripts/kernel-doc --sphinx-version 3.2.1 $files[$i] 2>/dev/null);
+ }
+
+ my @missing_exports;
+ my $found = -1;
+ foreach my $e (@exports) {
+ # Check if the symbol is a function
+ if (!($content =~ (m/\n\s*(?:\w+\s+){0,}\*?\s*\b\Q$e\E\b\s*\(/))) {
+ next;
+ }
+ for (my $i = 0; $i < scalar(@files); $i++) {
+ if ($doc[$i] =~ m/\b\Q$e\E\b/) {
+ $found = $i;
+ $doc_refs[$i]++;
+ last;
+ }
+ }
+
+ push @missing_exports, $e if ($found < 0);
+ }
+
+ if (@missing_exports) {
+ print "warning: $file: missing documentation for @missing_exports\n";
+ }
+
+ for (my $i = 0; $i < scalar(@files); $i++) {
+ next if (!$doc_refs[$i]);
+ my $includes = qx(git grep -l "kernel-doc::\\s*$files[$i]" Documentation/);
+
+ printf "warning: %s: file not included at Documentation/\n", $files[$i] if ($includes eq "");
+ }
+ return 1;
+}
+
+sub parse_dir {
+ check_file $File::Find::name;
+}
+
+#
+# main
+#
+
+my $file;
+
+if (@ARGV) {
+ while (@ARGV) {
+ my $file = shift;
+
+ if (-d $file) {
+ find({wanted => \&parse_dir, no_chdir => 1}, $file);
+ } else {
+ check_file $file;
+ }
+ }
+ exit;
+} else {
+ my @files = qx(git grep -l EXPORT_SYMBOL);
+ foreach $file (@files) {
+ $file =~ s/\s+$//;
+ check_file $file;
+ }
+}
--
2.26.2
