#!/usr/bin/perl -w use strict; ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved #### Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> #### Copyright (C) 2001 Simon Huggins #### Copyright (C) 2005-2012 Randy Dunlap #### Copyright (C) 2012 Dan Luedtke #### #### #define enhancements by Armin Kuster <akuster@mvista.com> #### Copyright (c) 2000 MontaVista Software, Inc. #### #### This software falls under the GNU General Public License. #### Please read the COPYING file for more information ## # 18/01/2001 - Cleanups# Functions prototyped as foo(void) same as foo()# Stop eval'ing where we don't need to.# -- huggie@earth.li # 27/06/2001 - Allowed whitespace after initial "/**" and# allowed comments before function declarations.# -- Christian Kreibich <ck@whoop.org> # Still to do:# - add perldoc documentation# - Look more closely at some of the scarier bits :) # 26/05/2001 - Support for separate source and object trees.# Return error code.# Keith Owens <kaos@ocs.com.au> # 23/09/2001 - Added support for typedefs, structs, enums and unions# Support for Context section; can be terminated using empty line# Small fixes (like spaces vs. \s in regex)# -- Tim Jansen <tim@tjansen.de> # 25/07/2012 - Added support for HTML5# -- Dan Luedtke <mail@danrl.de> sub usage { my $message = <<"EOF";Usage: $0 [OPTION ...] FILE ... Read C language source or header FILEs, extract embedded documentation comments,and print formatted documentation to standard output. The documentation comments are identified by "/**" opening comment mark. SeeDocumentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax. Output format selection (mutually exclusive): -docbook Output DocBook format. -html Output HTML format. -html5 Output HTML5 format. -list Output symbol list format. This is for use by docproc. -man Output troff manual page format. This is the default. -rst Output reStructuredText format. -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. -nofunction NAME Do NOT output documentation for the given function(s); only output documentation for the other functions and DOC: sections. May be specified multiple times. 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. -h Print this help. EOF print $message; exit 1;} ## format of comments.# In the following table, (...)? signifies optional structure.# (...)* signifies 0 or more structure elements# /**# * function_name(:)? (- short description)?# (* @parameterx: (description of parameter x)?)*# (* a blank line)?# * (Description:)? (Description of function)?# * (section header: (section description)? )*# (*)?*/## So .. the trivial example would be:## /**# * my_function# */## If the Description: header tag is omitted, then there must be a blank line# after the last parameter specification.# e.g.# /**# * my_function - does my stuff# * @my_arg: its mine damnit# *# * Does my stuff explained.# */## or, could also use:# /**# * my_function - does my stuff# * @my_arg: its mine damnit# * Description: Does my stuff explained.# */# etc.## Besides functions you can also write documentation for structs, unions,# enums and typedefs. Instead of the function name you must write the name# of the declaration; the struct/union/enum/typedef must always precede# the name. Nesting of declarations is not supported.# Use the argument mechanism to document members or constants.# e.g.# /**# * struct my_struct - short description# * @a: first member# * @b: second member# *# * Longer description# */# struct my_struct {# int a;# int b;# /* private: */# int c;# };## All descriptions can be multiline, except the short function description.## For really longs structs, you can also describe arguments inside the# body of the struct.# eg.# /**# * struct my_struct - short description# * @a: first member# * @b: second member# *# * Longer description# */# struct my_struct {# int a;# int b;# /**# * @c: This is longer description of C# *# * You can use paragraphs to describe arguments# * using this method.# */# int c;# };## This should be use only for struct/enum members.## You can also add additional sections. When documenting kernel functions you# should document the "Context:" of the function, e.g. whether the functions# can be called form interrupts. Unlike other sections you can end it with an# empty line.# A non-void function should have a "Return:" section describing the return# value(s).# Example-sections should contain the string EXAMPLE so that they are marked# appropriately in DocBook.## Example:# /**# * user_function - function that can only be called in user context# * @a: some argument# * Context: !in_interrupt()# *# * Some description# * Example:# * user_function(22);# */# ...### All descriptive text is further processed, scanning for the following special# patterns, which are highlighted appropriately.## 'funcname()' - function# '$ENVVAR' - environmental variable# '&struct_name' - name of a structure (up to two words including 'struct')# '@parameter' - name of a parameter# '%CONST' - name of a constant. ## init lots of data my $errors = 0;my $warnings = 0;my $anon_struct_union = 0; # match expressions used to find embedded type informationmy $type_constant = '\%([-_\w]+)';my $type_func = '(\w+)\(\)';my $type_param = '\@(\w+)';my $type_struct = '\&((struct\s*)*[_\w]+)';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 # these work fairly wellmy @highlights_html = ( [$type_constant, "<i>\$1</i>"], [$type_func, "<b>\$1</b>"], [$type_struct_xml, "<i>\$1</i>"], [$type_env, "<b><i>\$1</i></b>"], [$type_param, "<tt><b>\$1</b></tt>"] );my $local_lt = "\\\\\\\\lt:";my $local_gt = "\\\\\\\\gt:";my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>" # html version 5my @highlights_html5 = ( [$type_constant, "<span class=\"const\">\$1</span>"], [$type_func, "<span class=\"func\">\$1</span>"], [$type_struct_xml, "<span class=\"struct\">\$1</span>"], [$type_env, "<span class=\"env\">\$1</span>"], [$type_param, "<span class=\"param\">\$1</span>]"] );my $blankline_html5 = $local_lt . "br /" . $local_gt; # XML, docbook formatmy @highlights_xml = ( ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"], [$type_constant, "<constant>\$1</constant>"], [$type_struct_xml, "<structname>\$1</structname>"], [$type_param, "<parameter>\$1</parameter>"], [$type_func, "<function>\$1</function>"], [$type_env, "<envar>\$1</envar>"] );my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n"; # gnome, docbook formatmy @highlights_gnome = ( [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"], [$type_func, "<function>\$1</function>"], [$type_struct, "<structname>\$1</structname>"], [$type_env, "<envar>\$1</envar>"], [$type_param, "<parameter>\$1</parameter>" ] );my $blankline_gnome = "</para><para>\n"; # these are pretty roughmy @highlights_man = ( [$type_constant, "\$1"], [$type_func, "\\\\fB\$1\\\\fP"], [$type_struct, "\\\\fI\$1\\\\fP"], [$type_param, "\\\\fI\$1\\\\fP"] );my $blankline_man = ""; # text-modemy @highlights_text = ( [$type_constant, "\$1"], [$type_func, "\$1"], [$type_struct, "\$1"], [$type_param, "\$1"] );my $blankline_text = ""; # rst-modemy @highlights_rst = ( [$type_constant, "``\$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_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"; # list modemy @highlights_list = ( [$type_constant, "\$1"], [$type_func, "\$1"], [$type_struct, "\$1"], [$type_param, "\$1"] );my $blankline_list = ""; # read argumentsif ($#ARGV == -1) { usage();} my $kernelversion;my $dohighlight = ""; 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"; 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 '') { @build_time = gmtime($seconds);} else { @build_time = localtime;} my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December')[$build_time[4]] . " " . ($build_time[5]+1900); # Essentially these are globals.# They probably want to be tidied up, made more localised or something.# 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); if (defined($ENV{'KBUILD_VERBOSE'})) { $verbose = "$ENV{'KBUILD_VERBOSE'}";} # Generated docbook code is inserted in a template at a point where# docbook v3.1 requires a non-zero sequence of RefEntry's; see:# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html# We keep track of number of generated entries and generate a dummy# if needs be to ensure the expanded template can be postprocessed# into html.my $section_counter = 0; my $lineprefix=""; # Parser statesuse 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; # Inline documentation stateuse 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_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+)';# @params and a strictly limited set of supported section namesmy $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_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 %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 sectionmy $section_intro = "Introduction";my $section = $section_default;my $section_context = "Context";my $section_return = "Return"; my $undescribed = "-- undescribed --"; reset_state(); while ($ARGV[0] =~ m/^-(.*)/) { my $cmd = shift @ARGV; if ($cmd eq "-html") { $output_mode = "html"; @highlights = @highlights_html; $blankline = $blankline_html; } elsif ($cmd eq "-html5") { $output_mode = "html5"; @highlights = @highlights_html5; $blankline = $blankline_html5; } elsif ($cmd eq "-man") { $output_mode = "man"; @highlights = @highlights_man; $blankline = $blankline_man; } elsif ($cmd eq "-text") { $output_mode = "text"; @highlights = @highlights_text; $blankline = $blankline_text; } elsif ($cmd eq "-rst") { $output_mode = "rst"; @highlights = @highlights_rst; $blankline = $blankline_rst; } elsif ($cmd eq "-docbook") { $output_mode = "xml"; @highlights = @highlights_xml; $blankline = $blankline_xml; } elsif ($cmd eq "-list") { $output_mode = "list"; @highlights = @highlights_list; $blankline = $blankline_list; } elsif ($cmd eq "-gnome") { $output_mode = "gnome"; @highlights = @highlights_gnome; $blankline = $blankline_gnome; } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document $modulename = shift @ARGV; } elsif ($cmd eq "-function") { # to only output specific functions $output_selection = OUTPUT_INCLUDE; $function = shift @ARGV; $function_table{$function} = 1; } 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;Lines 1–500 of 3126. Load more
#!/usr/bin/perl -w use strict; ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ## ## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ## ## Copyright (C) 2001 Simon Huggins ## ## Copyright (C) 2005-2012 Randy Dunlap ## ## Copyright (C) 2012 Dan Luedtke ## ## ## ## #define enhancements by Armin Kuster <akuster@mvista.com> ## ## Copyright (c) 2000 MontaVista Software, Inc. ## ## ## ## This software falls under the GNU General Public License. ## ## Please read the COPYING file for more information ## # 18/01/2001 - Cleanups # Functions prototyped as foo(void) same as foo() # Stop eval'ing where we don't need to. # -- huggie@earth.li # 27/06/2001 - Allowed whitespace after initial "/**" and # allowed comments before function declarations. # -- Christian Kreibich <ck@whoop.org> # Still to do: # - add perldoc documentation # - Look more closely at some of the scarier bits :) # 26/05/2001 - Support for separate source and object trees. # Return error code. # Keith Owens <kaos@ocs.com.au> # 23/09/2001 - Added support for typedefs, structs, enums and unions # Support for Context section; can be terminated using empty line # Small fixes (like spaces vs. \s in regex) # -- Tim Jansen <tim@tjansen.de> # 25/07/2012 - Added support for HTML5 # -- Dan Luedtke <mail@danrl.de> sub usage { my $message = <<"EOF"; Usage: $0 [OPTION ...] FILE ... Read C language source or header FILEs, extract embedded documentation comments, and print formatted documentation to standard output. The documentation comments are identified by "/**" opening comment mark. See Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax. Output format selection (mutually exclusive): -docbook Output DocBook format. -html Output HTML format. -html5 Output HTML5 format. -list Output symbol list format. This is for use by docproc. -man Output troff manual page format. This is the default. -rst Output reStructuredText format. -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. -nofunction NAME Do NOT output documentation for the given function(s); only output documentation for the other functions and DOC: sections. May be specified multiple times. 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. -h Print this help. EOF print $message; exit 1; } # # format of comments. # In the following table, (...)? signifies optional structure. # (...)* signifies 0 or more structure elements # /** # * function_name(:)? (- short description)? # (* @parameterx: (description of parameter x)?)* # (* a blank line)? # * (Description:)? (Description of function)? # * (section header: (section description)? )* # (*)?*/ # # So .. the trivial example would be: # # /** # * my_function # */ # # If the Description: header tag is omitted, then there must be a blank line # after the last parameter specification. # e.g. # /** # * my_function - does my stuff # * @my_arg: its mine damnit # * # * Does my stuff explained. # */ # # or, could also use: # /** # * my_function - does my stuff # * @my_arg: its mine damnit # * Description: Does my stuff explained. # */ # etc. # # Besides functions you can also write documentation for structs, unions, # enums and typedefs. Instead of the function name you must write the name # of the declaration; the struct/union/enum/typedef must always precede # the name. Nesting of declarations is not supported. # Use the argument mechanism to document members or constants. # e.g. # /** # * struct my_struct - short description # * @a: first member # * @b: second member # * # * Longer description # */ # struct my_struct { # int a; # int b; # /* private: */ # int c; # }; # # All descriptions can be multiline, except the short function description. # # For really longs structs, you can also describe arguments inside the # body of the struct. # eg. # /** # * struct my_struct - short description # * @a: first member # * @b: second member # * # * Longer description # */ # struct my_struct { # int a; # int b; # /** # * @c: This is longer description of C # * # * You can use paragraphs to describe arguments # * using this method. # */ # int c; # }; # # This should be use only for struct/enum members. # # You can also add additional sections. When documenting kernel functions you # should document the "Context:" of the function, e.g. whether the functions # can be called form interrupts. Unlike other sections you can end it with an # empty line. # A non-void function should have a "Return:" section describing the return # value(s). # Example-sections should contain the string EXAMPLE so that they are marked # appropriately in DocBook. # # Example: # /** # * user_function - function that can only be called in user context # * @a: some argument # * Context: !in_interrupt() # * # * Some description # * Example: # * user_function(22); # */ # ... # # # All descriptive text is further processed, scanning for the following special # patterns, which are highlighted appropriately. # # 'funcname()' - function # '$ENVVAR' - environmental variable # '&struct_name' - name of a structure (up to two words including 'struct') # '@parameter' - name of a parameter # '%CONST' - name of a constant. ## init lots of data my $errors = 0; my $warnings = 0; my $anon_struct_union = 0; # match expressions used to find embedded type information my $type_constant = '\%([-_\w]+)'; my $type_func = '(\w+)\(\)'; my $type_param = '\@(\w+)'; my $type_struct = '\&((struct\s*)*[_\w]+)'; 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 # these work fairly well my @highlights_html = ( [$type_constant, "<i>\$1</i>"], [$type_func, "<b>\$1</b>"], [$type_struct_xml, "<i>\$1</i>"], [$type_env, "<b><i>\$1</i></b>"], [$type_param, "<tt><b>\$1</b></tt>"] ); my $local_lt = "\\\\\\\\lt:"; my $local_gt = "\\\\\\\\gt:"; my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>" # html version 5 my @highlights_html5 = ( [$type_constant, "<span class=\"const\">\$1</span>"], [$type_func, "<span class=\"func\">\$1</span>"], [$type_struct_xml, "<span class=\"struct\">\$1</span>"], [$type_env, "<span class=\"env\">\$1</span>"], [$type_param, "<span class=\"param\">\$1</span>]"] ); my $blankline_html5 = $local_lt . "br /" . $local_gt; # XML, docbook format my @highlights_xml = ( ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"], [$type_constant, "<constant>\$1</constant>"], [$type_struct_xml, "<structname>\$1</structname>"], [$type_param, "<parameter>\$1</parameter>"], [$type_func, "<function>\$1</function>"], [$type_env, "<envar>\$1</envar>"] ); my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n"; # gnome, docbook format my @highlights_gnome = ( [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"], [$type_func, "<function>\$1</function>"], [$type_struct, "<structname>\$1</structname>"], [$type_env, "<envar>\$1</envar>"], [$type_param, "<parameter>\$1</parameter>" ] ); my $blankline_gnome = "</para><para>\n"; # these are pretty rough my @highlights_man = ( [$type_constant, "\$1"], [$type_func, "\\\\fB\$1\\\\fP"], [$type_struct, "\\\\fI\$1\\\\fP"], [$type_param, "\\\\fI\$1\\\\fP"] ); my $blankline_man = ""; # text-mode my @highlights_text = ( [$type_constant, "\$1"], [$type_func, "\$1"], [$type_struct, "\$1"], [$type_param, "\$1"] ); my $blankline_text = ""; # rst-mode my @highlights_rst = ( [$type_constant, "``\$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_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"; # list mode my @highlights_list = ( [$type_constant, "\$1"], [$type_func, "\$1"], [$type_struct, "\$1"], [$type_param, "\$1"] ); my $blankline_list = ""; # read arguments if ($#ARGV == -1) { usage(); } my $kernelversion; my $dohighlight = ""; 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"; 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 '') { @build_time = gmtime($seconds); } else { @build_time = localtime; } my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December')[$build_time[4]] . " " . ($build_time[5]+1900); # Essentially these are globals. # They probably want to be tidied up, made more localised or something. # 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); if (defined($ENV{'KBUILD_VERBOSE'})) { $verbose = "$ENV{'KBUILD_VERBOSE'}"; } # Generated docbook code is inserted in a template at a point where # docbook v3.1 requires a non-zero sequence of RefEntry's; see: # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html # We keep track of number of generated entries and generate a dummy # if needs be to ensure the expanded template can be postprocessed # into html. my $section_counter = 0; my $lineprefix=""; # 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; # 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_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+)'; # @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_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 %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; my $section_context = "Context"; my $section_return = "Return"; my $undescribed = "-- undescribed --"; reset_state(); while ($ARGV[0] =~ m/^-(.*)/) { my $cmd = shift @ARGV; if ($cmd eq "-html") { $output_mode = "html"; @highlights = @highlights_html; $blankline = $blankline_html; } elsif ($cmd eq "-html5") { $output_mode = "html5"; @highlights = @highlights_html5; $blankline = $blankline_html5; } elsif ($cmd eq "-man") { $output_mode = "man"; @highlights = @highlights_man; $blankline = $blankline_man; } elsif ($cmd eq "-text") { $output_mode = "text"; @highlights = @highlights_text; $blankline = $blankline_text; } elsif ($cmd eq "-rst") { $output_mode = "rst"; @highlights = @highlights_rst; $blankline = $blankline_rst; } elsif ($cmd eq "-docbook") { $output_mode = "xml"; @highlights = @highlights_xml; $blankline = $blankline_xml; } elsif ($cmd eq "-list") { $output_mode = "list"; @highlights = @highlights_list; $blankline = $blankline_list; } elsif ($cmd eq "-gnome") { $output_mode = "gnome"; @highlights = @highlights_gnome; $blankline = $blankline_gnome; } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document $modulename = shift @ARGV; } elsif ($cmd eq "-function") { # to only output specific functions $output_selection = OUTPUT_INCLUDE; $function = shift @ARGV; $function_table{$function} = 1; } 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;