History

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 ...

Linus Torvalds committed 10 years ago

Commit 0f776dc2 parents 015cd86 a88b16730 files · +2653 −430Browse files

Showing the changes to scripts (1 of 30 files). Show all

Unified · Split

scripts/kernel-doc+306−151
@@ -59,6 +59,12 @@ Output format selection (mutually exclusive): · 58 unmodified lines
5959 -text Output plain text format.
6060
6161 Output selection (mutually exclusive):
62+ -export Only output documentation for symbols that have been
63+ exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
64+ in any input FILE or -export-file FILE.
65+ -internal Only output documentation for symbols that have NOT been
66+ exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
67+ in any input FILE or -export-file FILE.
6268 -function NAME Only output documentation for the given function(s)
6369 or DOC: section title(s). All other functions and DOC:
6470 sections are ignored. May be specified multiple times.
@@ -68,6 +74,11 @@ Output selection (mutually exclusive): · 3 unmodified lines
6874
6975 Output selection modifiers:
7076 -no-doc-sections Do not output DOC: sections.
77+ -enable-lineno Enable output of #define LINENO lines. Only works with
78+ reStructuredText format.
79+ -export-file FILE Specify an additional FILE in which to look for
80+ EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
81+ -export or -internal. May be specified multiple times.
7182
7283 Other parameters:
7384 -v Verbose output, more warnings and other information.
@@ -206,6 +217,10 @@ my $type_struct_xml = '\\&((struct\s*)*[_\w]+)'; · 132 unmodified lines
206217 my $type_env = '(\$\w+)';
207218 my $type_enum_full = '\&(enum)\s*([_\w]+)';
208219 my $type_struct_full = '\&(struct)\s*([_\w]+)';
220+my $type_typedef_full = '\&(typedef)\s*([_\w]+)';
221+my $type_union_full = '\&(union)\s*([_\w]+)';
222+my $type_member = '\&([_\w]+)((\.|->)[_\w]+)';
223+my $type_member_func = $type_member . '\(\)';
209224
210225 # Output conversion substitutions.
211226 # One for each output format
@@ -274,10 +289,16 @@ my $blankline_text = ""; · 62 unmodified lines
274289 # rst-mode
275290 my @highlights_rst = (
276291 [$type_constant, "``\$1``"],
277− [$type_func, "\\:c\\:func\\:`\$1`"],
292+ # Note: need to escape () to avoid func matching later
293+ [$type_member_func, "\\:c\\:type\\:`\$1\$2\\\\(\\\\) <\$1>`"],
294+ [$type_member, "\\:c\\:type\\:`\$1\$2 <\$1>`"],
295+ [$type_func, "\\:c\\:func\\:`\$1()`"],
278296 [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
279297 [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
280− [$type_struct, "\\:c\\:type\\:`struct \$1 <\$1>`"],
298+ [$type_typedef_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
299+ [$type_union_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
300+ # in rst this can refer to any type
301+ [$type_struct, "\\:c\\:type\\:`\$1`"],
281302 [$type_param, "**\$1**"]
282303 );
283304 my $blankline_rst = "\n";
@@ -303,12 +324,23 @@ my $verbose = 0; · 19 unmodified lines
303324 my $output_mode = "man";
304325 my $output_preformatted = 0;
305326 my $no_doc_sections = 0;
327+my $enable_lineno = 0;
306328 my @highlights = @highlights_man;
307329 my $blankline = $blankline_man;
308330 my $modulename = "Kernel API";
309−my $function_only = 0;
331+
332+use constant {
333+ OUTPUT_ALL => 0, # output all symbols and doc sections
334+ OUTPUT_INCLUDE => 1, # output only specified symbols
335+ OUTPUT_EXCLUDE => 2, # output everything except specified symbols
336+ OUTPUT_EXPORTED => 3, # output exported symbols
337+ OUTPUT_INTERNAL => 4, # output non-exported symbols
338+};
339+my $output_selection = OUTPUT_ALL;
310340 my $show_not_found = 0;
311341
342+my @export_file_list;
343+
312344 my @build_time;
313345 if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
314346 (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
@@ -327,6 +359,7 @@ my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', · 12 unmodified lines
327359 # CAVEAT EMPTOR! Some of the others I localised may not want to be, which
328360 # could cause "use of undefined value" or other bugs.
329361 my ($function, %function_table, %parametertypes, $declaration_purpose);
362+my $declaration_start_line;
330363 my ($type, $declaration_name, $return_type);
331364 my ($newsection, $newcontents, $prototype, $brcount, %source_map);
332365
@@ -344,52 +377,62 @@ my $section_counter = 0; · 11 unmodified lines
344377
345378 my $lineprefix="";
346379
347−# states
348−# 0 - normal code
349−# 1 - looking for function name
350−# 2 - scanning field start.
351−# 3 - scanning prototype.
352−# 4 - documentation block
353−# 5 - gathering documentation outside main block
380+# Parser states
381+use constant {
382+ STATE_NORMAL => 0, # normal code
383+ STATE_NAME => 1, # looking for function name
384+ STATE_FIELD => 2, # scanning field start
385+ STATE_PROTO => 3, # scanning prototype
386+ STATE_DOCBLOCK => 4, # documentation block
387+ STATE_INLINE => 5, # gathering documentation outside main block
388+};
354389 my $state;
355390 my $in_doc_sect;
356391
357−# Split Doc State
358−# 0 - Invalid (Before start or after finish)
359−# 1 - Is started (the /** was found inside a struct)
360−# 2 - The @parameter header was found, start accepting multi paragraph text.
361−# 3 - Finished (the */ was found)
362−# 4 - Error - Comment without header was found. Spit a warning as it's not
363−# proper kernel-doc and ignore the rest.
364−my $split_doc_state;
392+# Inline documentation state
393+use constant {
394+ STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)
395+ STATE_INLINE_NAME => 1, # looking for member name (@foo:)
396+ STATE_INLINE_TEXT => 2, # looking for member documentation
397+ STATE_INLINE_END => 3, # done
398+ STATE_INLINE_ERROR => 4, # error - Comment without header was found.
399+ # Spit a warning as it's not
400+ # proper kernel-doc and ignore the rest.
401+};
402+my $inline_doc_state;
365403
366404 #declaration types: can be
367405 # 'function', 'struct', 'union', 'enum', 'typedef'
368406 my $decl_type;
369407
370−my $doc_special = "\@\%\$\&";
371−
372408 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
373409 my $doc_end = '\*/';
374410 my $doc_com = '\s*\*\s*';
375411 my $doc_com_body = '\s*\* ?';
376412 my $doc_decl = $doc_com . '(\w+)';
377−my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
413+# @params and a strictly limited set of supported section names
414+my $doc_sect = $doc_com .
415+ '\s*(\@\w+|description|context|returns?|notes?|examples?)\s*:(.*)';
378416 my $doc_content = $doc_com_body . '(.*)';
379417 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
380−my $doc_split_start = '^\s*/\*\*\s*$';
381−my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)';
382−my $doc_split_end = '^\s*\*/\s*$';
418+my $doc_inline_start = '^\s*/\*\*\s*$';
419+my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
420+my $doc_inline_end = '^\s*\*/\s*$';
421+my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
383422
384−my %constants;
385423 my %parameterdescs;
424+my %parameterdesc_start_lines;
386425 my @parameterlist;
387426 my %sections;
388427 my @sectionlist;
428+my %section_start_lines;
389429 my $sectcheck;
390430 my $struct_actual;
391431
392432 my $contents = "";
433+my $new_start_line = 0;
434+
435+# the canonical section names. see also $doc_sect above.
393436 my $section_default = "Description"; # default section
394437 my $section_intro = "Introduction";
395438 my $section = $section_default;
@@ -437,19 +480,30 @@ while ($ARGV[0] =~ m/^-(.*)/) { · 41 unmodified lines
437480 } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
438481 $modulename = shift @ARGV;
439482 } elsif ($cmd eq "-function") { # to only output specific functions
440− $function_only = 1;
483+ $output_selection = OUTPUT_INCLUDE;
441484 $function = shift @ARGV;
442485 $function_table{$function} = 1;
443− } elsif ($cmd eq "-nofunction") { # to only output specific functions
444− $function_only = 2;
486+ } elsif ($cmd eq "-nofunction") { # output all except specific functions
487+ $output_selection = OUTPUT_EXCLUDE;
445488 $function = shift @ARGV;
446489 $function_table{$function} = 1;
490+ } elsif ($cmd eq "-export") { # only exported symbols
491+ $output_selection = OUTPUT_EXPORTED;
492+ %function_table = ();
493+ } elsif ($cmd eq "-internal") { # only non-exported symbols
494+ $output_selection = OUTPUT_INTERNAL;
495+ %function_table = ();
496+ } elsif ($cmd eq "-export-file") {
497+ my $file = shift @ARGV;
498+ push(@export_file_list, $file);
447499 } elsif ($cmd eq "-v") {
448500 $verbose = 1;
449501 } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
450502 usage();
451503 } elsif ($cmd eq '-no-doc-sections') {
452504 $no_doc_sections = 1;
505+ } elsif ($cmd eq '-enable-lineno') {
506+ $enable_lineno = 1;
453507 } elsif ($cmd eq '-show-not-found') {
454508 $show_not_found = 1;
455509 }
@@ -467,6 +521,13 @@ sub get_kernel_version() { · 11 unmodified lines
467521 return $version;
468522 }
469523
524+#
525+sub print_lineno {
526+ my $lineno = shift;
527+ if ($enable_lineno && defined($lineno)) {
528+ print "#define LINENO " . $lineno . "\n";
529+ }
530+}
470531 ##
471532 # dumps section contents to arrays/hashes intended for that purpose.
472533 #
@@ -475,28 +536,32 @@ sub dump_section { · 2 unmodified lines
475536 my $name = shift;
476537 my $contents = join "\n", @_;
477538
478− if ($name =~ m/$type_constant/) {
479− $name = $1;
480−# print STDERR "constant section '$1' = '$contents'\n";
481− $constants{$name} = $contents;
482− } elsif ($name =~ m/$type_param/) {
483−# print STDERR "parameter def '$1' = '$contents'\n";
539+ if ($name =~ m/$type_param/) {
484540 $name = $1;
485541 $parameterdescs{$name} = $contents;
486542 $sectcheck = $sectcheck . $name . " ";
543+ $parameterdesc_start_lines{$name} = $new_start_line;
544+ $new_start_line = 0;
487545 } elsif ($name eq "@\.\.\.") {
488−# print STDERR "parameter def '...' = '$contents'\n";
489546 $name = "...";
490547 $parameterdescs{$name} = $contents;
491548 $sectcheck = $sectcheck . $name . " ";
549+ $parameterdesc_start_lines{$name} = $new_start_line;
550+ $new_start_line = 0;
492551 } else {
493−# print STDERR "other section '$name' = '$contents'\n";
494552 if (defined($sections{$name}) && ($sections{$name} ne "")) {
495− print STDERR "${file}:$.: error: duplicate section name '$name'\n";
496− ++$errors;
553+ # Only warn on user specified duplicate section names.
554+ if ($name ne $section_default) {
555+ print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
556+ ++$warnings;
557+ }
558+ $sections{$name} .= $contents;
559+ } else {
560+ $sections{$name} = $contents;
561+ push @sectionlist, $name;
562+ $section_start_lines{$name} = $new_start_line;
563+ $new_start_line = 0;
497564 }
498− $sections{$name} = $contents;
499− push @sectionlist, $name;
500565 }
501566 }
502567
@@ -512,15 +577,17 @@ sub dump_doc_section { · 9 unmodified lines
512577 return;
513578 }
514579
515− if (($function_only == 0) ||
516− ( $function_only == 1 && defined($function_table{$name})) ||
517− ( $function_only == 2 && !defined($function_table{$name})))
580+ if (($output_selection == OUTPUT_ALL) ||
581+ ($output_selection == OUTPUT_INCLUDE &&
582+ defined($function_table{$name})) ||
583+ ($output_selection == OUTPUT_EXCLUDE &&
584+ !defined($function_table{$name})))
518585 {
519586 dump_section($file, $name, $contents);
520587 output_blockhead({'sectionlist' => \@sectionlist,
521588 'sections' => \%sections,
522589 'module' => $modulename,
523− 'content-only' => ($function_only != 0), });
590+ 'content-only' => ($output_selection != OUTPUT_ALL), });
524591 }
525592 }
526593
@@ -1736,7 +1803,10 @@ sub output_blockhead_rst(%) { · 1209 unmodified lines
17361803 my ($parameter, $section);
17371804
17381805 foreach $section (@{$args{'sectionlist'}}) {
1739− print "**$section**\n\n";
1806+ if ($output_selection != OUTPUT_INCLUDE) {
1807+ print "**$section**\n\n";
1808+ }
1809+ print_lineno($section_start_lines{$section});
17401810 output_highlight_rst($args{'sections'}{$section});
17411811 print "\n";
17421812 }
@@ -1753,19 +1823,14 @@ sub output_highlight_rst { · 10 unmodified lines
17531823 die $@ if $@;
17541824
17551825 foreach $line (split "\n", $contents) {
1756− if ($line eq "") {
1757− print $lineprefix, $blankline;
1758− } else {
1759− $line =~ s/\\\\\\/\&/g;
1760− print $lineprefix, $line;
1761− }
1762− print "\n";
1826+ print $lineprefix . $line . "\n";
17631827 }
17641828 }
17651829
17661830 sub output_function_rst(%) {
17671831 my %args = %{$_[0]};
17681832 my ($parameter, $section);
1833+ my $oldprefix = $lineprefix;
17691834 my $start;
17701835
17711836 print ".. c:function:: ";
@@ -1783,6 +1848,10 @@ sub output_function_rst(%) { · 11 unmodified lines
17831848 }
17841849 $count++;
17851850 $type = $args{'parametertypes'}{$parameter};
1851+
1852+ # RST doesn't like address_space tags at function prototypes
1853+ $type =~ s/__(user|kernel|iomem|percpu|pmem|rcu)\s*//;
1854+
17861855 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
17871856 # pointer-to-function
17881857 print $1 . $parameter . ") (" . $2;
@@ -1790,29 +1859,37 @@ sub output_function_rst(%) { · 1 unmodified line
17901859 print $type . " " . $parameter;
17911860 }
17921861 }
1793− print ")\n\n " . $args{'purpose'} . "\n\n";
1862+ print ")\n\n";
1863+ print_lineno($declaration_start_line);
1864+ $lineprefix = " ";
1865+ output_highlight_rst($args{'purpose'});
1866+ print "\n";
17941867
1795− print ":Parameters:\n\n";
1868+ print "**Parameters**\n\n";
1869+ $lineprefix = " ";
17961870 foreach $parameter (@{$args{'parameterlist'}}) {
17971871 my $parameter_name = $parameter;
17981872 #$parameter_name =~ s/\[.*//;
17991873 $type = $args{'parametertypes'}{$parameter};
18001874
18011875 if ($type ne "") {
1802− print " ``$type $parameter``\n";
1876+ print "``$type $parameter``\n";
18031877 } else {
1804− print " ``$parameter``\n";
1878+ print "``$parameter``\n";
18051879 }
1806− if ($args{'parameterdescs'}{$parameter_name} ne $undescribed) {
1807− my $oldprefix = $lineprefix;
1808− $lineprefix = " ";
1880+
1881+ print_lineno($parameterdesc_start_lines{$parameter_name});
1882+
1883+ if (defined($args{'parameterdescs'}{$parameter_name}) &&
1884+ $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
18091885 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1810− $lineprefix = $oldprefix;
18111886 } else {
1812− print "\n _undescribed_\n";
1887+ print " *undescribed*\n";
18131888 }
18141889 print "\n";
18151890 }
1891+
1892+ $lineprefix = $oldprefix;
18161893 output_section_rst(@_);
18171894 }
18181895
@@ -1820,10 +1897,11 @@ sub output_section_rst(%) { · 1 unmodified line
18201897 my %args = %{$_[0]};
18211898 my $section;
18221899 my $oldprefix = $lineprefix;
1823− $lineprefix = " ";
1900+ $lineprefix = "";
18241901
18251902 foreach $section (@{$args{'sectionlist'}}) {
1826− print ":$section:\n\n";
1903+ print "**$section**\n\n";
1904+ print_lineno($section_start_lines{$section});
18271905 output_highlight_rst($args{'sections'}{$section});
18281906 print "\n";
18291907 }
@@ -1834,24 +1912,28 @@ sub output_section_rst(%) { · 4 unmodified lines
18341912 sub output_enum_rst(%) {
18351913 my %args = %{$_[0]};
18361914 my ($parameter);
1915+ my $oldprefix = $lineprefix;
18371916 my $count;
18381917 my $name = "enum " . $args{'enum'};
18391918
18401919 print "\n\n.. c:type:: " . $name . "\n\n";
1841− print " " . $args{'purpose'} . "\n\n";
1920+ print_lineno($declaration_start_line);
1921+ $lineprefix = " ";
1922+ output_highlight_rst($args{'purpose'});
1923+ print "\n";
18421924
1843− print "..\n\n:Constants:\n\n";
1844− my $oldprefix = $lineprefix;
1845− $lineprefix = " ";
1925+ print "**Constants**\n\n";
1926+ $lineprefix = " ";
18461927 foreach $parameter (@{$args{'parameterlist'}}) {
1847− print " `$parameter`\n";
1928+ print "``$parameter``\n";
18481929 if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
18491930 output_highlight_rst($args{'parameterdescs'}{$parameter});
18501931 } else {
1851− print " undescribed\n";
1932+ print " *undescribed*\n";
18521933 }
18531934 print "\n";
18541935 }
1936+
18551937 $lineprefix = $oldprefix;
18561938 output_section_rst(@_);
18571939 }
@@ -1859,30 +1941,37 @@ sub output_enum_rst(%) { · 1 unmodified line
18591941 sub output_typedef_rst(%) {
18601942 my %args = %{$_[0]};
18611943 my ($parameter);
1862− my $count;
1944+ my $oldprefix = $lineprefix;
18631945 my $name = "typedef " . $args{'typedef'};
18641946
1865− ### FIXME: should the name below contain "typedef" or not?
18661947 print "\n\n.. c:type:: " . $name . "\n\n";
1867− print " " . $args{'purpose'} . "\n\n";
1948+ print_lineno($declaration_start_line);
1949+ $lineprefix = " ";
1950+ output_highlight_rst($args{'purpose'});
1951+ print "\n";
18681952
1953+ $lineprefix = $oldprefix;
18691954 output_section_rst(@_);
18701955 }
18711956
18721957 sub output_struct_rst(%) {
18731958 my %args = %{$_[0]};
18741959 my ($parameter);
1960+ my $oldprefix = $lineprefix;
18751961 my $name = $args{'type'} . " " . $args{'struct'};
18761962
18771963 print "\n\n.. c:type:: " . $name . "\n\n";
1878− print " " . $args{'purpose'} . "\n\n";
1964+ print_lineno($declaration_start_line);
1965+ $lineprefix = " ";
1966+ output_highlight_rst($args{'purpose'});
1967+ print "\n";
18791968
1880− print ":Definition:\n\n";
1881− print " ::\n\n";
1969+ print "**Definition**\n\n";
1970+ print "::\n\n";
18821971 print " " . $args{'type'} . " " . $args{'struct'} . " {\n";
18831972 foreach $parameter (@{$args{'parameterlist'}}) {
18841973 if ($parameter =~ /^#/) {
1885− print " " . "$parameter\n";
1974+ print " " . "$parameter\n";
18861975 next;
18871976 }
18881977
@@ -1903,7 +1992,8 @@ sub output_struct_rst(%) { · 14 unmodified lines
19031992 }
19041993 print " };\n\n";
19051994
1906− print ":Members:\n\n";
1995+ print "**Members**\n\n";
1996+ $lineprefix = " ";
19071997 foreach $parameter (@{$args{'parameterlist'}}) {
19081998 ($parameter =~ /^#/) && next;
19091999
@@ -1912,14 +2002,14 @@ sub output_struct_rst(%) { · 2 unmodified lines
19122002
19132003 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
19142004 $type = $args{'parametertypes'}{$parameter};
1915− print " `$type $parameter`" . "\n";
1916− my $oldprefix = $lineprefix;
1917− $lineprefix = " ";
2005+ print_lineno($parameterdesc_start_lines{$parameter_name});
2006+ print "``$type $parameter``\n";
19182007 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1919− $lineprefix = $oldprefix;
19202008 print "\n";
19212009 }
19222010 print "\n";
2011+
2012+ $lineprefix = $oldprefix;
19232013 output_section_rst(@_);
19242014 }
19252015
@@ -1969,9 +2059,13 @@ sub output_declaration { · 43 unmodified lines
19692059 my $name = shift;
19702060 my $functype = shift;
19712061 my $func = "output_${functype}_$output_mode";
1972− if (($function_only==0) ||
1973− ( $function_only == 1 && defined($function_table{$name})) ||
1974− ( $function_only == 2 && !($functype eq "function" && defined($function_table{$name}))))
2062+ if (($output_selection == OUTPUT_ALL) ||
2063+ (($output_selection == OUTPUT_INCLUDE ||
2064+ $output_selection == OUTPUT_EXPORTED) &&
2065+ defined($function_table{$name})) ||
2066+ (($output_selection == OUTPUT_EXCLUDE ||
2067+ $output_selection == OUTPUT_INTERNAL) &&
2068+ !($functype eq "function" && defined($function_table{$name}))))
19752069 {
19762070 &$func(@_);
19772071 $section_counter++;
@@ -2471,7 +2565,6 @@ sub dump_function($$) { · 493 unmodified lines
24712565
24722566 sub reset_state {
24732567 $function = "";
2474− %constants = ();
24752568 %parameterdescs = ();
24762569 %parametertypes = ();
24772570 @parameterlist = ();
@@ -2481,8 +2574,8 @@ sub reset_state { · 3 unmodified lines
24812574 $struct_actual = "";
24822575 $prototype = "";
24832576
2484− $state = 0;
2485− $split_doc_state = 0;
2577+ $state = STATE_NORMAL;
2578+ $inline_doc_state = STATE_INLINE_NA;
24862579 }
24872580
24882581 sub tracepoint_munge($) {
@@ -2545,7 +2638,7 @@ sub syscall_munge() { · 56 unmodified lines
25452638 }
25462639 }
25472640
2548−sub process_state3_function($$) {
2641+sub process_proto_function($$) {
25492642 my $x = shift;
25502643 my $file = shift;
25512644
@@ -2575,7 +2668,7 @@ sub process_state3_function($$) { · 23 unmodified lines
25752668 }
25762669 }
25772670
2578−sub process_state3_type($$) {
2671+sub process_proto_type($$) {
25792672 my $x = shift;
25802673 my $file = shift;
25812674
@@ -2649,25 +2742,54 @@ sub local_unescape($) { · 67 unmodified lines
26492742 return $text;
26502743 }
26512744
2652−sub process_file($) {
2745+sub map_filename($) {
26532746 my $file;
2654− my $identifier;
2655− my $func;
2656− my $descr;
2657− my $in_purpose = 0;
2658− my $initial_section_counter = $section_counter;
26592747 my ($orig_file) = @_;
26602748
26612749 if (defined($ENV{'SRCTREE'})) {
26622750 $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
2663− }
2664− else {
2751+ } else {
26652752 $file = $orig_file;
26662753 }
2754+
26672755 if (defined($source_map{$file})) {
26682756 $file = $source_map{$file};
26692757 }
26702758
2759+ return $file;
2760+}
2761+
2762+sub process_export_file($) {
2763+ my ($orig_file) = @_;
2764+ my $file = map_filename($orig_file);
2765+
2766+ if (!open(IN,"<$file")) {
2767+ print STDERR "Error: Cannot open file $file\n";
2768+ ++$errors;
2769+ return;
2770+ }
2771+
2772+ while (<IN>) {
2773+ if (/$export_symbol/) {
2774+ $function_table{$2} = 1;
2775+ }
2776+ }
2777+
2778+ close(IN);
2779+}
2780+
2781+sub process_file($) {
2782+ my $file;
2783+ my $identifier;
2784+ my $func;
2785+ my $descr;
2786+ my $in_purpose = 0;
2787+ my $initial_section_counter = $section_counter;
2788+ my ($orig_file) = @_;
2789+ my $leading_space;
2790+
2791+ $file = map_filename($orig_file);
2792+
26712793 if (!open(IN,"<$file")) {
26722794 print STDERR "Error: Cannot open file $file\n";
26732795 ++$errors;
@@ -2681,15 +2803,18 @@ sub process_file($) { · 7 unmodified lines
26812803 while (s/\\\s*$//) {
26822804 $_ .= <IN>;
26832805 }
2684− if ($state == 0) {
2806+ if ($state == STATE_NORMAL) {
26852807 if (/$doc_start/o) {
2686− $state = 1; # next line is always the function name
2808+ $state = STATE_NAME; # next line is always the function name
26872809 $in_doc_sect = 0;
2810+ $declaration_start_line = $. + 1;
26882811 }
2689− } elsif ($state == 1) { # this line is the function name (always)
2812+ } elsif ($state == STATE_NAME) {# this line is the function name (always)
26902813 if (/$doc_block/o) {
2691− $state = 4;
2814+ $state = STATE_DOCBLOCK;
26922815 $contents = "";
2816+ $new_start_line = $. + 1;
2817+
26932818 if ( $1 eq "" ) {
26942819 $section = $section_intro;
26952820 } else {
@@ -2702,7 +2827,12 @@ sub process_file($) { · 6 unmodified lines
27022827 $identifier = $1;
27032828 }
27042829
2705− $state = 2;
2830+ $state = STATE_FIELD;
2831+ # if there's no @param blocks need to set up default section
2832+ # here
2833+ $contents = "";
2834+ $section = $section_default;
2835+ $new_start_line = $. + 1;
27062836 if (/-(.*)/) {
27072837 # strip leading/trailing/multiple spaces
27082838 $descr= $1;
@@ -2740,13 +2870,25 @@ sub process_file($) { · 31 unmodified lines
27402870 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
27412871 " - I thought it was a doc line\n";
27422872 ++$warnings;
2743− $state = 0;
2873+ $state = STATE_NORMAL;
27442874 }
2745− } elsif ($state == 2) { # look for head: lines, and include content
2746− if (/$doc_sect/o) {
2875+ } elsif ($state == STATE_FIELD) { # look for head: lines, and include content
2876+ if (/$doc_sect/i) { # case insensitive for supported section names
27472877 $newsection = $1;
27482878 $newcontents = $2;
27492879
2880+ # map the supported section names to the canonical names
2881+ if ($newsection =~ m/^description$/i) {
2882+ $newsection = $section_default;
2883+ } elsif ($newsection =~ m/^context$/i) {
2884+ $newsection = $section_context;
2885+ } elsif ($newsection =~ m/^returns?$/i) {
2886+ $newsection = $section_return;
2887+ } elsif ($newsection =~ m/^\@return$/) {
2888+ # special: @return is a section, not a param description
2889+ $newsection = $section_return;
2890+ }
2891+
27502892 if (($contents ne "") && ($contents ne "\n")) {
27512893 if (!$in_doc_sect && $verbose) {
27522894 print STDERR "${file}:$.: warning: contents before sections\n";
@@ -2759,14 +2901,16 @@ sub process_file($) { · 6 unmodified lines
27592901 $in_doc_sect = 1;
27602902 $in_purpose = 0;
27612903 $contents = $newcontents;
2904+ $new_start_line = $.;
2905+ while ((substr($contents, 0, 1) eq " ") ||
2906+ substr($contents, 0, 1) eq "\t") {
2907+ $contents = substr($contents, 1);
2908+ }
27622909 if ($contents ne "") {
2763− while ((substr($contents, 0, 1) eq " ") ||
2764− substr($contents, 0, 1) eq "\t") {
2765− $contents = substr($contents, 1);
2766− }
27672910 $contents .= "\n";
27682911 }
27692912 $section = $newsection;
2913+ $leading_space = undef;
27702914 } elsif (/$doc_end/) {
27712915 if (($contents ne "") && ($contents ne "\n")) {
27722916 dump_section($file, $section, xml_escape($contents));
@@ -2780,7 +2924,7 @@ sub process_file($) { · 7 unmodified lines
27802924 }
27812925
27822926 $prototype = "";
2783− $state = 3;
2927+ $state = STATE_PROTO;
27842928 $brcount = 0;
27852929 # print STDERR "end of doc comment, looking for prototype\n";
27862930 } elsif (/$doc_content/) {
@@ -2791,6 +2935,7 @@ sub process_file($) { · 4 unmodified lines
27912935 dump_section($file, $section, xml_escape($contents));
27922936 $section = $section_default;
27932937 $contents = "";
2938+ $new_start_line = $.;
27942939 } else {
27952940 $contents .= "\n";
27962941 }
@@ -2801,87 +2946,86 @@ sub process_file($) { · 4 unmodified lines
28012946 $declaration_purpose .= " " . xml_escape($1);
28022947 $declaration_purpose =~ s/\s+/ /g;
28032948 } else {
2804− $contents .= $1 . "\n";
2949+ my $cont = $1;
2950+ if ($section =~ m/^@/ || $section eq $section_context) {
2951+ if (!defined $leading_space) {
2952+ if ($cont =~ m/^(\s+)/) {
2953+ $leading_space = $1;
2954+ } else {
2955+ $leading_space = "";
2956+ }
2957+ }
2958+
2959+ $cont =~ s/^$leading_space//;
2960+ }
2961+ $contents .= $cont . "\n";
28052962 }
28062963 } else {
28072964 # i dont know - bad line? ignore.
28082965 print STDERR "${file}:$.: warning: bad line: $_";
28092966 ++$warnings;
28102967 }
2811− } elsif ($state == 5) { # scanning for split parameters
2968+ } elsif ($state == STATE_INLINE) { # scanning for inline parameters
28122969 # First line (state 1) needs to be a @parameter
2813− if ($split_doc_state == 1 && /$doc_split_sect/o) {
2970+ if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
28142971 $section = $1;
28152972 $contents = $2;
2973+ $new_start_line = $.;
28162974 if ($contents ne "") {
28172975 while ((substr($contents, 0, 1) eq " ") ||
28182976 substr($contents, 0, 1) eq "\t") {
28192977 $contents = substr($contents, 1);
28202978 }
2821− $contents .= "\n";
2979+ $contents .= "\n";
28222980 }
2823− $split_doc_state = 2;
2981+ $inline_doc_state = STATE_INLINE_TEXT;
28242982 # Documentation block end */
2825− } elsif (/$doc_split_end/) {
2983+ } elsif (/$doc_inline_end/) {
28262984 if (($contents ne "") && ($contents ne "\n")) {
28272985 dump_section($file, $section, xml_escape($contents));
28282986 $section = $section_default;
28292987 $contents = "";
28302988 }
2831− $state = 3;
2832− $split_doc_state = 0;
2989+ $state = STATE_PROTO;
2990+ $inline_doc_state = STATE_INLINE_NA;
28332991 # Regular text
28342992 } elsif (/$doc_content/) {
2835− if ($split_doc_state == 2) {
2993+ if ($inline_doc_state == STATE_INLINE_TEXT) {
28362994 $contents .= $1 . "\n";
2837− } elsif ($split_doc_state == 1) {
2838− $split_doc_state = 4;
2839− print STDERR "Warning(${file}:$.): ";
2995+ # nuke leading blank lines
2996+ if ($contents =~ /^\s*$/) {
2997+ $contents = "";
2998+ }
2999+ } elsif ($inline_doc_state == STATE_INLINE_NAME) {
3000+ $inline_doc_state = STATE_INLINE_ERROR;
3001+ print STDERR "${file}:$.: warning: ";
28403002 print STDERR "Incorrect use of kernel-doc format: $_";
28413003 ++$warnings;
28423004 }
28433005 }
2844− } elsif ($state == 3) { # scanning for function '{' (end of prototype)
2845− if (/$doc_split_start/) {
2846− $state = 5;
2847− $split_doc_state = 1;
3006+ } elsif ($state == STATE_PROTO) { # scanning for function '{' (end of prototype)
3007+ if (/$doc_inline_start/) {
3008+ $state = STATE_INLINE;
3009+ $inline_doc_state = STATE_INLINE_NAME;
28483010 } elsif ($decl_type eq 'function') {
2849− process_state3_function($_, $file);
3011+ process_proto_function($_, $file);
28503012 } else {
2851− process_state3_type($_, $file);
3013+ process_proto_type($_, $file);
28523014 }
2853− } elsif ($state == 4) {
2854− # Documentation block
2855− if (/$doc_block/) {
2856− dump_doc_section($file, $section, xml_escape($contents));
2857− $contents = "";
2858− $function = "";
2859− %constants = ();
2860− %parameterdescs = ();
2861− %parametertypes = ();
2862− @parameterlist = ();
2863− %sections = ();
2864− @sectionlist = ();
2865− $prototype = "";
2866− if ( $1 eq "" ) {
2867− $section = $section_intro;
2868− } else {
2869− $section = $1;
2870− }
2871− }
2872− elsif (/$doc_end/)
3015+ } elsif ($state == STATE_DOCBLOCK) {
3016+ if (/$doc_end/)
28733017 {
28743018 dump_doc_section($file, $section, xml_escape($contents));
3019+ $section = $section_default;
28753020 $contents = "";
28763021 $function = "";
2877− %constants = ();
28783022 %parameterdescs = ();
28793023 %parametertypes = ();
28803024 @parameterlist = ();
28813025 %sections = ();
28823026 @sectionlist = ();
28833027 $prototype = "";
2884− $state = 0;
3028+ $state = STATE_NORMAL;
28853029 }
28863030 elsif (/$doc_content/)
28873031 {
@@ -2898,7 +3042,7 @@ sub process_file($) { · 10 unmodified lines
28983042 }
28993043 if ($initial_section_counter == $section_counter) {
29003044 print STDERR "${file}:1: warning: no structured comments found\n";
2901− if (($function_only == 1) && ($show_not_found == 1)) {
3045+ if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
29023046 print STDERR " Was looking for '$_'.\n" for keys %function_table;
29033047 }
29043048 if ($output_mode eq "xml") {
@@ -2957,6 +3101,17 @@ if (open(SOURCE_MAP, "<.tmp_filelist.txt")) { · 52 unmodified lines
29573101 close(SOURCE_MAP);
29583102 }
29593103
3104+if ($output_selection == OUTPUT_EXPORTED ||
3105+ $output_selection == OUTPUT_INTERNAL) {
3106+
3107+ push(@export_file_list, @ARGV);
3108+
3109+ foreach (@export_file_list) {
3110+ chomp;
3111+ process_export_file($_);
3112+ }
3113+}
3114+
29603115 foreach (@ARGV) {
29613116 chomp;
29623117 process_file($_);