Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1317814

[RFC 03/10] kernel-doc: support printing exported and non-exported symbols

Show all headers | View raw

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.

[This should cover most of the cases. If it's not enough, it's trivial
to allow specifying additional files to look for EXPORT_SYMBOL* in.]

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 scripts/kernel-doc | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 15077f910e81..ee2ac9137a43 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")) {
@@ -1976,8 +1989,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++;
@@ -2682,6 +2697,16 @@ sub process_file($) {
 
     $. = 1;
 
+    # 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);
+    }
+
     $section_counter = 0;
     while (<IN>) {
 	while (s/\\\s*$//) {
-- 
2.1.4

Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

[RFC] A first shot at asciidoc-based formatted docs Jonathan Corbet <corbet@lwn.net> - 2016-01-26 00:30 +0100
  [PATCH 1/4] kernel-doc: add support for asciidoc output Jonathan Corbet <corbet@lwn.net> - 2016-01-26 00:30 +0100
  [PATCH 2/4] docproc: handle asciidoc templates Jonathan Corbet <corbet@lwn.net> - 2016-01-26 00:30 +0100
  [PATCH 3/4] Docs: Makefile tweaks for asciidoc templates Jonathan Corbet <corbet@lwn.net> - 2016-01-26 00:30 +0100
  [PATCH 4/4] Docs: add a sample asciidoc template Jonathan Corbet <corbet@lwn.net> - 2016-01-26 00:30 +0100
  [RFC 10/10] Documentation: build asciidoc documentation Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:10 +0100
  Re: [RFC] A first shot at asciidoc-based formatted docs Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:10 +0100
    [RFC 09/10] Documentation: convert gpu.tmpl to gpu.txt Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:10 +0100
    [RFC 05/10] scripts: add asciidoc-includes to extract includes from asciidoc Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:10 +0100
    [RFC 06/10] scripts: add a kernel-doc helper for special invocation Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:10 +0100
    [RFC 04/10] kernel-doc: add support for printing DOC: comments with escaped names Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:20 +0100
    [RFC 01/10] kernel-doc: rewrite usage description, remove duplicated comments Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:20 +0100
    Re: [RFC] A first shot at asciidoc-based formatted docs Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-01-26 13:20 +0100
      Re: [RFC] A first shot at asciidoc-based formatted docs Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:40 +0100
    [RFC 03/10] kernel-doc: support printing exported and non-exported symbols Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:20 +0100
    [RFC 07/10] scripts: add tool for generating asciidoc dependencies and rules Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:20 +0100
    [RFC 08/10] scripts: add a crude converter from DocBook tmpl to asciidoc Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:20 +0100
    [RFC 02/10] kernel-doc: add support for asciidoc output Jani Nikula <jani.nikula@intel.com> - 2016-01-26 13:20 +0100
    Re: [RFC] A first shot at asciidoc-based formatted docs Jonathan Corbet <corbet@lwn.net> - 2016-01-26 15:50 +0100
      Re: [RFC] A first shot at asciidoc-based formatted docs Jonathan Corbet <corbet@lwn.net> - 2016-01-26 16:00 +0100

csiph-web