summaryrefslogtreecommitdiff
path: root/scripts/kernel-doc
diff options
context:
space:
mode:
authorJani Nikula <jani.nikula@intel.com>2016-01-21 13:05:22 +0200
committerJani Nikula <jani.nikula@intel.com>2016-05-30 13:38:50 +0300
commit86ae2e38d40ed6bf7c907d126053e6f4b1dc5b6e (patch)
tree190122e6829a2de86b5bffcf9515887ced329fb3 /scripts/kernel-doc
parent5e64fa9c441ff273f39527f4014d3c3e724d321a (diff)
kernel-doc: support printing exported and non-exported symbols
Currently we use docproc to figure out which symbols are exported, and then docproc calls kernel-doc on specific functions, to get documentation on exported functions. According to git blame and docproc comments, this is due to historical reasons, as functions and their corresponding EXPORT_SYMBOL* may have been in different files. However for more than ten years the recommendation in CodingStyle has been to place the EXPORT_SYMBOL* immediately after the closing function brace line. Additionally, the kernel-doc comments for functions are generally placed above the function definition in the .c files (i.e. where the EXPORT_SYMBOL* is) rather than above the declaration in the .h files. There are some exceptions to this, but AFAICT none of these are included in DocBook documentation using the "!E" docproc directive. Therefore, assuming the EXPORT_SYMBOL* and kernel-doc are with the function definition, kernel-doc can extract the exported vs. not information by making two passes on the input file. Add support for that via the new -export and -internal parameters. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Diffstat (limited to 'scripts/kernel-doc')
-rwxr-xr-xscripts/kernel-doc29
1 files changed, 27 insertions, 2 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index babb374c043d..3ad54abe0989 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -59,6 +59,12 @@ Output format selection (mutually exclusive):
-text Output plain text format.
Output selection (mutually exclusive):
+ -export Only output documentation for symbols that have been
+ exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
+ in the same FILE.
+ -internal Only output documentation for symbols that have NOT been
+ exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
+ in the same FILE.
-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.
@@ -380,6 +386,7 @@ my $doc_block = $doc_com . 'DOC:\s*(.*)?';
my $doc_split_start = '^\s*/\*\*\s*$';
my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)';
my $doc_split_end = '^\s*\*/\s*$';
+my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
my %constants;
my %parameterdescs;
@@ -444,6 +451,12 @@ while ($ARGV[0] =~ m/^-(.*)/) {
$function_only = 2;
$function = shift @ARGV;
$function_table{$function} = 1;
+ } elsif ($cmd eq "-export") { # only exported symbols
+ $function_only = 3;
+ %function_table = ()
+ } elsif ($cmd eq "-internal") { # only non-exported symbols
+ $function_only = 4;
+ %function_table = ()
} elsif ($cmd eq "-v") {
$verbose = 1;
} elsif (($cmd eq "-h") || ($cmd eq "--help")) {
@@ -1971,8 +1984,10 @@ sub output_declaration {
my $functype = shift;
my $func = "output_${functype}_$output_mode";
if (($function_only==0) ||
- ( $function_only == 1 && defined($function_table{$name})) ||
- ( $function_only == 2 && !($functype eq "function" && defined($function_table{$name}))))
+ ( ($function_only == 1 || $function_only == 3) &&
+ defined($function_table{$name})) ||
+ ( ($function_only == 2 || $function_only == 4) &&
+ !($functype eq "function" && defined($function_table{$name}))))
{
&$func(@_);
$section_counter++;
@@ -2675,6 +2690,16 @@ sub process_file($) {
return;
}
+ # two passes for -export and -internal
+ if ($function_only == 3 || $function_only == 4) {
+ while (<IN>) {
+ if (/$export_symbol/o) {
+ $function_table{$2} = 1;
+ }
+ }
+ seek(IN, 0, 0);
+ }
+
$. = 1;
$section_counter = 0;