Merge tag 'docs-for-linus' of git://git.lwn.net/linux

Pull documentation updates from Jonathan Corbet:
 "Some big changes this month, headlined by the addition of a new
  formatted documentation mechanism based on the Sphinx system.

  The objectives here are to make it easier to create better-integrated
  (and more attractive) documents while (eventually) dumping our
  one-of-a-kind, cobbled-together system for something that is widely
  used and maintained by others.  There's a fair amount of information
  what's being done, why, and how to use it in:

    https://lwn.net/Articles/692704/
    https://lwn.net/Articles/692705/

  Closer to home, Documentation/kernel-documentation.rst describes how
  it works.

  For now, the new system exists alongside the old one; you should soon
  see the GPU documentation converted over in the DRM pull and some
  significant media conversion work as well.  Once all the docs have
  been moved over and we're convinced that the rough edges (of which are
  are a few) have been smoothed over, the DocBook-based stuff should go
  away.

  Primary credit is to Jani Nikula for doing the heavy lifting to make
  this stuff actually work; there has also been notable effort from
  Markus Heiser, Daniel Vetter, and Mauro Carvalho Chehab.

  Expect a couple of conflicts on the new index.rst file over the course
  of the merge window; they are trivially resolvable.  That file may be
  a bit of a conflict magnet in the short term, but I don't expect that
  situation to last for any real length of time.

  Beyond that, of course, we have the usual collection of tweaks,
  updates, and typo fixes"

* tag 'docs-for-linus' of git://git.lwn.net/linux: (77 commits)
  doc-rst: kernel-doc: fix handling of address_space tags
  Revert "doc/sphinx: Enable keep_warnings"
  doc-rst: kernel-doc directive, fix state machine reporter
  docs: deprecate kernel-doc-nano-HOWTO.txt
  doc/sphinx: Enable keep_warnings
  Documentation: add watermark_scale_factor to the list of vm systcl file
  kernel-doc: Fix up warning output
  docs: Get rid of some kernel-documentation warnings
  doc-rst: add an option to ignore DocBooks when generating docs
  workqueue: Fix a typo in workqueue.txt
  Doc: ocfs: Fix typo in filesystems/ocfs2-online-filecheck.txt
  Documentation/sphinx: skip build if user requested specific DOCBOOKS
  Documentation: add cleanmediadocs to the documentation targets
  Add .pyc files to .gitignore
  Doc: PM: Fix a typo in intel_powerclamp.txt
  doc-rst: flat-table directive - initial implementation
  Documentation: add meta-documentation for Sphinx and kernel-doc
  Documentation: tiny typo fix in usb/gadget_multi.txt
  Documentation: fix wrong value in md.txt
  bcache: documentation formatting, edited for clarity, stripe alignment notes
  ...

1 files changed, 306 insertions, 151 deletions

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 2fc8fad5195e..4f2e9049e8fa 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 any input FILE or -export-file FILE.
+  -internal             Only output documentation for symbols that have NOT been
+                        exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
+                        in any input FILE or -export-file 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.
@@ -68,6 +74,11 @@ Output selection (mutually exclusive):
 
 Output selection modifiers:
   -no-doc-sections      Do not output DOC: sections.
+  -enable-lineno        Enable output of #define LINENO lines. Only works with
+                        reStructuredText format.
+  -export-file FILE     Specify an additional FILE in which to look for
+                        EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
+                        -export or -internal. May be specified multiple times.
 
 Other parameters:
   -v                    Verbose output, more warnings and other information.
@@ -206,6 +217,10 @@ my $type_struct_xml = '\\&((struct\s*)*[_\w]+)';
 my $type_env = '(\$\w+)';
 my $type_enum_full = '\&(enum)\s*([_\w]+)';
 my $type_struct_full = '\&(struct)\s*([_\w]+)';
+my $type_typedef_full = '\&(typedef)\s*([_\w]+)';
+my $type_union_full = '\&(union)\s*([_\w]+)';
+my $type_member = '\&([_\w]+)((\.|->)[_\w]+)';
+my $type_member_func = $type_member . '\(\)';
 
 # Output conversion substitutions.
 #  One for each output format
@@ -274,10 +289,16 @@ my $blankline_text = "";
 # rst-mode
 my @highlights_rst = (
                        [$type_constant, "``\$1``"],
-                       [$type_func, "\\:c\\:func\\:`\$1`"],
+                       # Note: need to escape () to avoid func matching later
+                       [$type_member_func, "\\:c\\:type\\:`\$1\$2\\\\(\\\\) <\$1>`"],
+                       [$type_member, "\\:c\\:type\\:`\$1\$2 <\$1>`"],
+                       [$type_func, "\\:c\\:func\\:`\$1()`"],
                        [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
                        [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
-                       [$type_struct, "\\:c\\:type\\:`struct \$1 <\$1>`"],
+                       [$type_typedef_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
+                       [$type_union_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
+                       # in rst this can refer to any type
+                       [$type_struct, "\\:c\\:type\\:`\$1`"],
                        [$type_param, "**\$1**"]
                       );
 my $blankline_rst = "\n";
@@ -303,12 +324,23 @@ my $verbose = 0;
 my $output_mode = "man";
 my $output_preformatted = 0;
 my $no_doc_sections = 0;
+my $enable_lineno = 0;
 my @highlights = @highlights_man;
 my $blankline = $blankline_man;
 my $modulename = "Kernel API";
-my $function_only = 0;
+
+use constant {
+    OUTPUT_ALL          => 0, # output all symbols and doc sections
+    OUTPUT_INCLUDE      => 1, # output only specified symbols
+    OUTPUT_EXCLUDE      => 2, # output everything except specified symbols
+    OUTPUT_EXPORTED     => 3, # output exported symbols
+    OUTPUT_INTERNAL     => 4, # output non-exported symbols
+};
+my $output_selection = OUTPUT_ALL;
 my $show_not_found = 0;
 
+my @export_file_list;
+
 my @build_time;
 if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
     (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
@@ -327,6 +359,7 @@ my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
 # CAVEAT EMPTOR!  Some of the others I localised may not want to be, which
 # could cause "use of undefined value" or other bugs.
 my ($function, %function_table, %parametertypes, $declaration_purpose);
+my $declaration_start_line;
 my ($type, $declaration_name, $return_type);
 my ($newsection, $newcontents, $prototype, $brcount, %source_map);
 
@@ -344,52 +377,62 @@ my $section_counter = 0;
 
 my $lineprefix="";
 
-# states
-# 0 - normal code
-# 1 - looking for function name
-# 2 - scanning field start.
-# 3 - scanning prototype.
-# 4 - documentation block
-# 5 - gathering documentation outside main block
+# Parser states
+use constant {
+    STATE_NORMAL        => 0, # normal code
+    STATE_NAME          => 1, # looking for function name
+    STATE_FIELD         => 2, # scanning field start
+    STATE_PROTO         => 3, # scanning prototype
+    STATE_DOCBLOCK      => 4, # documentation block
+    STATE_INLINE        => 5, # gathering documentation outside main block
+};
 my $state;
 my $in_doc_sect;
 
-# Split Doc State
-# 0 - Invalid (Before start or after finish)
-# 1 - Is started (the /** was found inside a struct)
-# 2 - The @parameter header was found, start accepting multi paragraph text.
-# 3 - Finished (the */ was found)
-# 4 - Error - Comment without header was found. Spit a warning as it's not
-#     proper kernel-doc and ignore the rest.
-my $split_doc_state;
+# Inline documentation state
+use constant {
+    STATE_INLINE_NA     => 0, # not applicable ($state != STATE_INLINE)
+    STATE_INLINE_NAME   => 1, # looking for member name (@foo:)
+    STATE_INLINE_TEXT   => 2, # looking for member documentation
+    STATE_INLINE_END    => 3, # done
+    STATE_INLINE_ERROR  => 4, # error - Comment without header was found.
+                              # Spit a warning as it's not
+                              # proper kernel-doc and ignore the rest.
+};
+my $inline_doc_state;
 
 #declaration types: can be
 # 'function', 'struct', 'union', 'enum', 'typedef'
 my $decl_type;
 
-my $doc_special = "\@\%\$\&";
-
 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
 my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
 my $doc_com_body = '\s*\* ?';
 my $doc_decl = $doc_com . '(\w+)';
-my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
+# @params and a strictly limited set of supported section names
+my $doc_sect = $doc_com . 
+    '\s*(\@\w+|description|context|returns?|notes?|examples?)\s*:(.*)';
 my $doc_content = $doc_com_body . '(.*)';
 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 $doc_inline_start = '^\s*/\*\*\s*$';
+my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
+my $doc_inline_end = '^\s*\*/\s*$';
+my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
 
-my %constants;
 my %parameterdescs;
+my %parameterdesc_start_lines;
 my @parameterlist;
 my %sections;
 my @sectionlist;
+my %section_start_lines;
 my $sectcheck;
 my $struct_actual;
 
 my $contents = "";
+my $new_start_line = 0;
+
+# the canonical section names. see also $doc_sect above.
 my $section_default = "Description";    # default section
 my $section_intro = "Introduction";
 my $section = $section_default;
@@ -437,19 +480,30 @@ while ($ARGV[0] =~ m/^-(.*)/) {
     } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
         $modulename = shift @ARGV;
     } elsif ($cmd eq "-function") { # to only output specific functions
-        $function_only = 1;
+        $output_selection = OUTPUT_INCLUDE;
         $function = shift @ARGV;
         $function_table{$function} = 1;
-    } elsif ($cmd eq "-nofunction") { # to only output specific functions
-        $function_only = 2;
+    } elsif ($cmd eq "-nofunction") { # output all except specific functions
+        $output_selection = OUTPUT_EXCLUDE;
         $function = shift @ARGV;
         $function_table{$function} = 1;
+    } elsif ($cmd eq "-export") { # only exported symbols
+        $output_selection = OUTPUT_EXPORTED;
+        %function_table = ();
+    } elsif ($cmd eq "-internal") { # only non-exported symbols
+        $output_selection = OUTPUT_INTERNAL;
+        %function_table = ();
+    } elsif ($cmd eq "-export-file") {
+        my $file = shift @ARGV;
+        push(@export_file_list, $file);
     } elsif ($cmd eq "-v") {
         $verbose = 1;
     } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
         usage();
     } elsif ($cmd eq '-no-doc-sections') {
             $no_doc_sections = 1;
+    } elsif ($cmd eq '-enable-lineno') {
+            $enable_lineno = 1;
     } elsif ($cmd eq '-show-not-found') {
         $show_not_found = 1;
     }
@@ -467,6 +521,13 @@ sub get_kernel_version() {
     return $version;
 }
 
+#
+sub print_lineno {
+    my $lineno = shift;
+    if ($enable_lineno && defined($lineno)) {
+        print "#define LINENO " . $lineno . "\n";
+    }
+}
 ##
 # dumps section contents to arrays/hashes intended for that purpose.
 #
@@ -475,28 +536,32 @@ sub dump_section {
     my $name = shift;
     my $contents = join "\n", @_;
 
-    if ($name =~ m/$type_constant/) {
-        $name = $1;
-#       print STDERR "constant section '$1' = '$contents'\n";
-        $constants{$name} = $contents;
-    } elsif ($name =~ m/$type_param/) {
-#       print STDERR "parameter def '$1' = '$contents'\n";
+    if ($name =~ m/$type_param/) {
         $name = $1;
         $parameterdescs{$name} = $contents;
         $sectcheck = $sectcheck . $name . " ";
+        $parameterdesc_start_lines{$name} = $new_start_line;
+        $new_start_line = 0;
     } elsif ($name eq "@\.\.\.") {
-#       print STDERR "parameter def '...' = '$contents'\n";
         $name = "...";
         $parameterdescs{$name} = $contents;
         $sectcheck = $sectcheck . $name . " ";
+        $parameterdesc_start_lines{$name} = $new_start_line;
+        $new_start_line = 0;
     } else {
-#       print STDERR "other section '$name' = '$contents'\n";
         if (defined($sections{$name}) && ($sections{$name} ne "")) {
-                print STDERR "${file}:$.: error: duplicate section name '$name'\n";
-                ++$errors;
+            # Only warn on user specified duplicate section names.
+            if ($name ne $section_default) {
+                print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
+                ++$warnings;
+            }
+            $sections{$name} .= $contents;
+        } else {
+            $sections{$name} = $contents;
+            push @sectionlist, $name;
+            $section_start_lines{$name} = $new_start_line;
+            $new_start_line = 0;
         }
-        $sections{$name} = $contents;
-        push @sectionlist, $name;
     }
 }
 
@@ -512,15 +577,17 @@ sub dump_doc_section {
         return;
     }
 
-    if (($function_only == 0) ||
-        ( $function_only == 1 && defined($function_table{$name})) ||
-        ( $function_only == 2 && !defined($function_table{$name})))
+    if (($output_selection == OUTPUT_ALL) ||
+        ($output_selection == OUTPUT_INCLUDE &&
+         defined($function_table{$name})) ||
+        ($output_selection == OUTPUT_EXCLUDE &&
+         !defined($function_table{$name})))
     {
         dump_section($file, $name, $contents);
         output_blockhead({'sectionlist' => \@sectionlist,
                           'sections' => \%sections,
                           'module' => $modulename,
-                          'content-only' => ($function_only != 0), });
+                          'content-only' => ($output_selection != OUTPUT_ALL), });
     }
 }
 
@@ -1736,7 +1803,10 @@ sub output_blockhead_rst(%) {
     my ($parameter, $section);
 
     foreach $section (@{$args{'sectionlist'}}) {
-        print "**$section**\n\n";
+        if ($output_selection != OUTPUT_INCLUDE) {
+            print "**$section**\n\n";
+        }
+        print_lineno($section_start_lines{$section});
         output_highlight_rst($args{'sections'}{$section});
         print "\n";
     }
@@ -1753,19 +1823,14 @@ sub output_highlight_rst {
     die $@ if $@;
 
     foreach $line (split "\n", $contents) {
-        if ($line eq "") {
-            print $lineprefix, $blankline;
-        } else {
-            $line =~ s/\\\\\\/\&/g;
-            print $lineprefix, $line;
-        }
-        print "\n";
+        print $lineprefix . $line . "\n";
     }
 }
 
 sub output_function_rst(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
+    my $oldprefix = $lineprefix;
     my $start;
 
     print ".. c:function:: ";
@@ -1783,6 +1848,10 @@ sub output_function_rst(%) {
         }
         $count++;
         $type = $args{'parametertypes'}{$parameter};
+
+        # RST doesn't like address_space tags at function prototypes
+        $type =~ s/__(user|kernel|iomem|percpu|pmem|rcu)\s*//;
+
         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
             # pointer-to-function
             print $1 . $parameter . ") (" . $2;
@@ -1790,29 +1859,37 @@ sub output_function_rst(%) {
             print $type . " " . $parameter;
         }
     }
-    print ")\n\n    " . $args{'purpose'} . "\n\n";
+    print ")\n\n";
+    print_lineno($declaration_start_line);
+    $lineprefix = "   ";
+    output_highlight_rst($args{'purpose'});
+    print "\n";
 
-    print ":Parameters:\n\n";
+    print "**Parameters**\n\n";
+    $lineprefix = "  ";
     foreach $parameter (@{$args{'parameterlist'}}) {
         my $parameter_name = $parameter;
         #$parameter_name =~ s/\[.*//;
         $type = $args{'parametertypes'}{$parameter};
 
         if ($type ne "") {
-            print "      ``$type $parameter``\n";
+            print "``$type $parameter``\n";
         } else {
-            print "      ``$parameter``\n";
+            print "``$parameter``\n";
         }
-        if ($args{'parameterdescs'}{$parameter_name} ne $undescribed) {
-            my $oldprefix = $lineprefix;
-            $lineprefix = "        ";
+
+        print_lineno($parameterdesc_start_lines{$parameter_name});
+
+        if (defined($args{'parameterdescs'}{$parameter_name}) &&
+            $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
             output_highlight_rst($args{'parameterdescs'}{$parameter_name});
-            $lineprefix = $oldprefix;
         } else {
-            print "\n        _undescribed_\n";
+            print "  *undescribed*\n";
         }
         print "\n";
     }
+
+    $lineprefix = $oldprefix;
     output_section_rst(@_);
 }
 
@@ -1820,10 +1897,11 @@ sub output_section_rst(%) {
     my %args = %{$_[0]};
     my $section;
     my $oldprefix = $lineprefix;
-    $lineprefix = "        ";
+    $lineprefix = "";
 
     foreach $section (@{$args{'sectionlist'}}) {
-        print ":$section:\n\n";
+        print "**$section**\n\n";
+        print_lineno($section_start_lines{$section});
         output_highlight_rst($args{'sections'}{$section});
         print "\n";
     }
@@ -1834,24 +1912,28 @@ sub output_section_rst(%) {
 sub output_enum_rst(%) {
     my %args = %{$_[0]};
     my ($parameter);
+    my $oldprefix = $lineprefix;
     my $count;
     my $name = "enum " . $args{'enum'};
 
     print "\n\n.. c:type:: " . $name . "\n\n";
-    print "    " . $args{'purpose'} . "\n\n";
+    print_lineno($declaration_start_line);
+    $lineprefix = "   ";
+    output_highlight_rst($args{'purpose'});
+    print "\n";
 
-    print "..\n\n:Constants:\n\n";
-    my $oldprefix = $lineprefix;
-    $lineprefix = "    ";
+    print "**Constants**\n\n";
+    $lineprefix = "  ";
     foreach $parameter (@{$args{'parameterlist'}}) {
-        print "  `$parameter`\n";
+        print "``$parameter``\n";
         if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
             output_highlight_rst($args{'parameterdescs'}{$parameter});
         } else {
-            print "    undescribed\n";
+            print "  *undescribed*\n";
         }
         print "\n";
     }
+
     $lineprefix = $oldprefix;
     output_section_rst(@_);
 }
@@ -1859,30 +1941,37 @@ sub output_enum_rst(%) {
 sub output_typedef_rst(%) {
     my %args = %{$_[0]};
     my ($parameter);
-    my $count;
+    my $oldprefix = $lineprefix;
     my $name = "typedef " . $args{'typedef'};
 
-    ### FIXME: should the name below contain "typedef" or not?
     print "\n\n.. c:type:: " . $name . "\n\n";
-    print "    " . $args{'purpose'} . "\n\n";
+    print_lineno($declaration_start_line);
+    $lineprefix = "   ";
+    output_highlight_rst($args{'purpose'});
+    print "\n";
 
+    $lineprefix = $oldprefix;
     output_section_rst(@_);
 }
 
 sub output_struct_rst(%) {
     my %args = %{$_[0]};
     my ($parameter);
+    my $oldprefix = $lineprefix;
     my $name = $args{'type'} . " " . $args{'struct'};
 
     print "\n\n.. c:type:: " . $name . "\n\n";
-    print "    " . $args{'purpose'} . "\n\n";
+    print_lineno($declaration_start_line);
+    $lineprefix = "   ";
+    output_highlight_rst($args{'purpose'});
+    print "\n";
 
-    print ":Definition:\n\n";
-    print " ::\n\n";
+    print "**Definition**\n\n";
+    print "::\n\n";
     print "  " . $args{'type'} . " " . $args{'struct'} . " {\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
         if ($parameter =~ /^#/) {
-            print "    " . "$parameter\n";
+            print "  " . "$parameter\n";
             next;
         }
 
@@ -1903,7 +1992,8 @@ sub output_struct_rst(%) {
     }
     print "  };\n\n";
 
-    print ":Members:\n\n";
+    print "**Members**\n\n";
+    $lineprefix = "  ";
     foreach $parameter (@{$args{'parameterlist'}}) {
         ($parameter =~ /^#/) && next;
 
@@ -1912,14 +2002,14 @@ sub output_struct_rst(%) {
 
         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
         $type = $args{'parametertypes'}{$parameter};
-        print "      `$type $parameter`" . "\n";
-        my $oldprefix = $lineprefix;
-        $lineprefix = "        ";
+        print_lineno($parameterdesc_start_lines{$parameter_name});
+        print "``$type $parameter``\n";
         output_highlight_rst($args{'parameterdescs'}{$parameter_name});
-        $lineprefix = $oldprefix;
         print "\n";
     }
     print "\n";
+
+    $lineprefix = $oldprefix;
     output_section_rst(@_);
 }
 
@@ -1969,9 +2059,13 @@ sub output_declaration {
     my $name = shift;
     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}))))
+    if (($output_selection == OUTPUT_ALL) ||
+        (($output_selection == OUTPUT_INCLUDE ||
+          $output_selection == OUTPUT_EXPORTED) &&
+         defined($function_table{$name})) ||
+        (($output_selection == OUTPUT_EXCLUDE ||
+          $output_selection == OUTPUT_INTERNAL) &&
+         !($functype eq "function" && defined($function_table{$name}))))
     {
         &$func(@_);
         $section_counter++;
@@ -2471,7 +2565,6 @@ sub dump_function($$) {
 
 sub reset_state {
     $function = "";
-    %constants = ();
     %parameterdescs = ();
     %parametertypes = ();
     @parameterlist = ();
@@ -2481,8 +2574,8 @@ sub reset_state {
     $struct_actual = "";
     $prototype = "";
 
-    $state = 0;
-    $split_doc_state = 0;
+    $state = STATE_NORMAL;
+    $inline_doc_state = STATE_INLINE_NA;
 }
 
 sub tracepoint_munge($) {
@@ -2545,7 +2638,7 @@ sub syscall_munge() {
         }
 }
 
-sub process_state3_function($$) {
+sub process_proto_function($$) {
     my $x = shift;
     my $file = shift;
 
@@ -2575,7 +2668,7 @@ sub process_state3_function($$) {
     }
 }
 
-sub process_state3_type($$) {
+sub process_proto_type($$) {
     my $x = shift;
     my $file = shift;
 
@@ -2649,25 +2742,54 @@ sub local_unescape($) {
         return $text;
 }
 
-sub process_file($) {
+sub map_filename($) {
     my $file;
-    my $identifier;
-    my $func;
-    my $descr;
-    my $in_purpose = 0;
-    my $initial_section_counter = $section_counter;
     my ($orig_file) = @_;
 
     if (defined($ENV{'SRCTREE'})) {
         $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
-    }
-    else {
+    } else {
         $file = $orig_file;
     }
+
     if (defined($source_map{$file})) {
         $file = $source_map{$file};
     }
 
+    return $file;
+}
+
+sub process_export_file($) {
+    my ($orig_file) = @_;
+    my $file = map_filename($orig_file);
+
+    if (!open(IN,"<$file")) {
+        print STDERR "Error: Cannot open file $file\n";
+        ++$errors;
+        return;
+    }
+
+    while (<IN>) {
+        if (/$export_symbol/) {
+            $function_table{$2} = 1;
+        }
+    }
+
+    close(IN);
+}
+
+sub process_file($) {
+    my $file;
+    my $identifier;
+    my $func;
+    my $descr;
+    my $in_purpose = 0;
+    my $initial_section_counter = $section_counter;
+    my ($orig_file) = @_;
+    my $leading_space;
+
+    $file = map_filename($orig_file);
+
     if (!open(IN,"<$file")) {
         print STDERR "Error: Cannot open file $file\n";
         ++$errors;
@@ -2681,15 +2803,18 @@ sub process_file($) {
         while (s/\\\s*$//) {
             $_ .= <IN>;
         }
-        if ($state == 0) {
+        if ($state == STATE_NORMAL) {
             if (/$doc_start/o) {
-                $state = 1;             # next line is always the function name
+                $state = STATE_NAME;    # next line is always the function name
                 $in_doc_sect = 0;
+                $declaration_start_line = $. + 1;
             }
-        } elsif ($state == 1) { # this line is the function name (always)
+        } elsif ($state == STATE_NAME) {# this line is the function name (always)
             if (/$doc_block/o) {
-                $state = 4;
+                $state = STATE_DOCBLOCK;
                 $contents = "";
+                $new_start_line = $. + 1;
+
                 if ( $1 eq "" ) {
                         $section = $section_intro;
                 } else {
@@ -2702,7 +2827,12 @@ sub process_file($) {
                     $identifier = $1;
                 }
 
-                $state = 2;
+                $state = STATE_FIELD;
+                # if there's no @param blocks need to set up default section
+                # here
+                $contents = "";
+                $section = $section_default;
+                $new_start_line = $. + 1;
                 if (/-(.*)/) {
                     # strip leading/trailing/multiple spaces
                     $descr= $1;
@@ -2740,13 +2870,25 @@ sub process_file($) {
                 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
                 " - I thought it was a doc line\n";
                 ++$warnings;
-                $state = 0;
+                $state = STATE_NORMAL;
             }
-        } elsif ($state == 2) { # look for head: lines, and include content
-            if (/$doc_sect/o) {
+        } elsif ($state == STATE_FIELD) {       # look for head: lines, and include content
+            if (/$doc_sect/i) { # case insensitive for supported section names
                 $newsection = $1;
                 $newcontents = $2;
 
+                # map the supported section names to the canonical names
+                if ($newsection =~ m/^description$/i) {
+                    $newsection = $section_default;
+                } elsif ($newsection =~ m/^context$/i) {
+                    $newsection = $section_context;
+                } elsif ($newsection =~ m/^returns?$/i) {
+                    $newsection = $section_return;
+                } elsif ($newsection =~ m/^\@return$/) {
+                    # special: @return is a section, not a param description
+                    $newsection = $section_return;
+                }
+
                 if (($contents ne "") && ($contents ne "\n")) {
                     if (!$in_doc_sect && $verbose) {
                         print STDERR "${file}:$.: warning: contents before sections\n";
@@ -2759,14 +2901,16 @@ sub process_file($) {
                 $in_doc_sect = 1;
                 $in_purpose = 0;
                 $contents = $newcontents;
+                $new_start_line = $.;
+                while ((substr($contents, 0, 1) eq " ") ||
+                       substr($contents, 0, 1) eq "\t") {
+                    $contents = substr($contents, 1);
+                }
                 if ($contents ne "") {
-                    while ((substr($contents, 0, 1) eq " ") ||
-                        substr($contents, 0, 1) eq "\t") {
-                            $contents = substr($contents, 1);
-                    }
                     $contents .= "\n";
                 }
                 $section = $newsection;
+                $leading_space = undef;
             } elsif (/$doc_end/) {
                 if (($contents ne "") && ($contents ne "\n")) {
                     dump_section($file, $section, xml_escape($contents));
@@ -2780,7 +2924,7 @@ sub process_file($) {
                 }
 
                 $prototype = "";
-                $state = 3;
+                $state = STATE_PROTO;
                 $brcount = 0;
 #               print STDERR "end of doc comment, looking for prototype\n";
             } elsif (/$doc_content/) {
@@ -2791,6 +2935,7 @@ sub process_file($) {
                         dump_section($file, $section, xml_escape($contents));
                         $section = $section_default;
                         $contents = "";
+                        $new_start_line = $.;
                     } else {
                         $contents .= "\n";
                     }
@@ -2801,87 +2946,86 @@ sub process_file($) {
                     $declaration_purpose .= " " . xml_escape($1);
                     $declaration_purpose =~ s/\s+/ /g;
                 } else {
-                    $contents .= $1 . "\n";
+                    my $cont = $1;
+                    if ($section =~ m/^@/ || $section eq $section_context) {
+                        if (!defined $leading_space) {
+                            if ($cont =~ m/^(\s+)/) {
+                                $leading_space = $1;
+                            } else {
+                                $leading_space = "";
+                            }
+                        }
+
+                        $cont =~ s/^$leading_space//;
+                    }
+                    $contents .= $cont . "\n";
                 }
             } else {
                 # i dont know - bad line?  ignore.
                 print STDERR "${file}:$.: warning: bad line: $_";
                 ++$warnings;
             }
-        } elsif ($state == 5) { # scanning for split parameters
+        } elsif ($state == STATE_INLINE) { # scanning for inline parameters
             # First line (state 1) needs to be a @parameter
-            if ($split_doc_state == 1 && /$doc_split_sect/o) {
+            if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
                 $section = $1;
                 $contents = $2;
+                $new_start_line = $.;
                 if ($contents ne "") {
                     while ((substr($contents, 0, 1) eq " ") ||
                            substr($contents, 0, 1) eq "\t") {
                         $contents = substr($contents, 1);
                     }
-                $contents .= "\n";
+                    $contents .= "\n";
                 }
-                $split_doc_state = 2;
+                $inline_doc_state = STATE_INLINE_TEXT;
             # Documentation block end */
-            } elsif (/$doc_split_end/) {
+            } elsif (/$doc_inline_end/) {
                 if (($contents ne "") && ($contents ne "\n")) {
                     dump_section($file, $section, xml_escape($contents));
                     $section = $section_default;
                     $contents = "";
                 }
-                $state = 3;
-                $split_doc_state = 0;
+                $state = STATE_PROTO;
+                $inline_doc_state = STATE_INLINE_NA;
             # Regular text
             } elsif (/$doc_content/) {
-                if ($split_doc_state == 2) {
+                if ($inline_doc_state == STATE_INLINE_TEXT) {
                     $contents .= $1 . "\n";
-                } elsif ($split_doc_state == 1) {
-                    $split_doc_state = 4;
-                    print STDERR "Warning(${file}:$.): ";
+                    # nuke leading blank lines
+                    if ($contents =~ /^\s*$/) {
+                        $contents = "";
+                    }
+                } elsif ($inline_doc_state == STATE_INLINE_NAME) {
+                    $inline_doc_state = STATE_INLINE_ERROR;
+                    print STDERR "${file}:$.: warning: ";
                     print STDERR "Incorrect use of kernel-doc format: $_";
                     ++$warnings;
                 }
             }
-        } elsif ($state == 3) { # scanning for function '{' (end of prototype)
-            if (/$doc_split_start/) {
-                $state = 5;
-                $split_doc_state = 1;
+        } elsif ($state == STATE_PROTO) {       # scanning for function '{' (end of prototype)
+            if (/$doc_inline_start/) {
+                $state = STATE_INLINE;
+                $inline_doc_state = STATE_INLINE_NAME;
             } elsif ($decl_type eq 'function') {
-                process_state3_function($_, $file);
+                process_proto_function($_, $file);
             } else {
-                process_state3_type($_, $file);
+                process_proto_type($_, $file);
             }
-        } elsif ($state == 4) {
-                # Documentation block
-                if (/$doc_block/) {
-                        dump_doc_section($file, $section, xml_escape($contents));
-                        $contents = "";
-                        $function = "";
-                        %constants = ();
-                        %parameterdescs = ();
-                        %parametertypes = ();
-                        @parameterlist = ();
-                        %sections = ();
-                        @sectionlist = ();
-                        $prototype = "";
-                        if ( $1 eq "" ) {
-                                $section = $section_intro;
-                        } else {
-                                $section = $1;
-                        }
-                }
-                elsif (/$doc_end/)
+        } elsif ($state == STATE_DOCBLOCK) {
+                if (/$doc_end/)
                 {
                         dump_doc_section($file, $section, xml_escape($contents));
+                        $section = $section_default;
                         $contents = "";
                         $function = "";
-                        %constants = ();
                         %parameterdescs = ();
                         %parametertypes = ();
                         @parameterlist = ();
                         %sections = ();
                         @sectionlist = ();
                         $prototype = "";
-                        $state = 0;
+                        $state = STATE_NORMAL;
                 }
                 elsif (/$doc_content/)
                 {
@@ -2898,7 +3042,7 @@ sub process_file($) {
     }
     if ($initial_section_counter == $section_counter) {
         print STDERR "${file}:1: warning: no structured comments found\n";
-        if (($function_only == 1) && ($show_not_found == 1)) {
+        if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
             print STDERR "    Was looking for '$_'.\n" for keys %function_table;
         }
         if ($output_mode eq "xml") {
@@ -2957,6 +3101,17 @@ if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
         close(SOURCE_MAP);
 }
 
+if ($output_selection == OUTPUT_EXPORTED ||
+    $output_selection == OUTPUT_INTERNAL) {
+
+    push(@export_file_list, @ARGV);
+
+    foreach (@export_file_list) {
+        chomp;
+        process_export_file($_);
+    }
+}
+
 foreach (@ARGV) {
     chomp;
     process_file($_);