p71924506
/
linux_old1
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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>
This commit is contained in:
Jani Nikula 2016-01-21 13:05:22 +02:00
parent 5e64fa9c44
commit 86ae2e38d4
1 changed files with 27 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
scripts/kernel-doc
View File

@ -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;