#!/usr/bin/env perl# SPDX-License-Identifier: GPL-2.0 use warnings;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/doc-guide/kernel-doc.rst for the documentation comment syntax. Output format selection (mutually exclusive): -man Output troff manual page format. This is the default. -rst Output reStructuredText format. -none Do not output documentation, only warnings. 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')# '&struct_name.member' - name of a structure member# '@parameter' - name of a parameter# '%CONST' - name of a constant.# '``LITERAL``' - literal string without any spaces on it. ## 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 = '\b``([^\`]+)``\b';my $type_constant2 = '\%([-_\w]+)';my $type_func = '(\w+)\(\)';my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr paramsmy $type_env = '(\$\w+)';my $type_enum = '\&(enum\s*([_\w]+))';my $type_struct = '\&(struct\s*([_\w]+))';my $type_typedef = '\&(typedef\s*([_\w]+))';my $type_union = '\&(union\s*([_\w]+))';my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';my $type_fallback = '\&([_\w]+)';my $type_member_func = $type_member . '\(\)'; # Output conversion substitutions.# One for each output format # these are pretty roughmy @highlights_man = ( [$type_constant, "\$1"], [$type_constant2, "\$1"], [$type_func, "\\\\fB\$1\\\\fP"], [$type_enum, "\\\\fI\$1\\\\fP"], [$type_struct, "\\\\fI\$1\\\\fP"], [$type_typedef, "\\\\fI\$1\\\\fP"], [$type_union, "\\\\fI\$1\\\\fP"], [$type_param, "\\\\fI\$1\\\\fP"], [$type_member, "\\\\fI\$1\$2\$3\\\\fP"], [$type_fallback, "\\\\fI\$1\\\\fP"] );my $blankline_man = ""; # rst-modemy @highlights_rst = ( [$type_constant, "``\$1``"], [$type_constant2, "``\$1``"], # Note: need to escape () to avoid func matching later [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"], [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"], [$type_fp_param, "**\$1\\\\(\\\\)**"], [$type_func, "\$1()"], [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"], [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"], [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"], [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"], # in rst this can refer to any type [$type_fallback, "\\:c\\:type\\:`\$1`"], [$type_param, "**\$1**"] );my $blankline_rst = "\n"; # read argumentsif ($#ARGV == -1) { usage();} my $kernelversion;my $dohighlight = ""; my $verbose = 0;my $output_mode = "rst";my $output_preformatted = 0;my $no_doc_sections = 0;my $enable_lineno = 0;my @highlights = @highlights_rst;my $blankline = $blankline_rst;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; # No longer used 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_BODY_MAYBE => 2, # body - or maybe more description STATE_BODY => 3, # the body of the comment STATE_PROTO => 4, # scanning prototype STATE_DOCBLOCK => 5, # documentation block STATE_INLINE => 6, # gathering documentation outside main block};my $state;my $in_doc_sect;my $leading_space; # 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*(@\s*[\w][\w\.]*\s*):(.*)';my $doc_inline_end = '^\s*\*/\s*$';my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\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 = $1; shift @ARGV; if ($cmd eq "man") { $output_mode = "man"; @highlights = @highlights_man; $blankline = $blankline_man; } elsif ($cmd eq "rst") { $output_mode = "rst"; @highlights = @highlights_rst; $blankline = $blankline_rst; } elsif ($cmd eq "none") { $output_mode = "none"; } 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; } 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; # A no-op but don't fail } else { # Unknown argument usage(); }} # continue execution near EOF; # get kernel version from envsub get_kernel_version() { my $version = 'unknown kernel version'; if (defined($ENV{'KERNELVERSION'})) { $version = $ENV{'KERNELVERSION'}; } 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.#sub dump_section { my $file = shift; my $name = shift; my $contents = join "\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 "@\.\.\.") { $name = "..."; $parameterdescs{$name} = $contents; $sectcheck = $sectcheck . $name . " "; $parameterdesc_start_lines{$name} = $new_start_line; $new_start_line = 0; } else { if (defined($sections{$name}) && ($sections{$name} ne "")) { # 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; } }} Lines 1–500 of 2225. Load more
#!/usr/bin/env perl # SPDX-License-Identifier: GPL-2.0 use warnings; 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/doc-guide/kernel-doc.rst for the documentation comment syntax. Output format selection (mutually exclusive): -man Output troff manual page format. This is the default. -rst Output reStructuredText format. -none Do not output documentation, only warnings. 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') # '&struct_name.member' - name of a structure member # '@parameter' - name of a parameter # '%CONST' - name of a constant. # '``LITERAL``' - literal string without any spaces on it. ## 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 = '\b``([^\`]+)``\b'; my $type_constant2 = '\%([-_\w]+)'; my $type_func = '(\w+)\(\)'; my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)'; my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params my $type_env = '(\$\w+)'; my $type_enum = '\&(enum\s*([_\w]+))'; my $type_struct = '\&(struct\s*([_\w]+))'; my $type_typedef = '\&(typedef\s*([_\w]+))'; my $type_union = '\&(union\s*([_\w]+))'; my $type_member = '\&([_\w]+)(\.|->)([_\w]+)'; my $type_fallback = '\&([_\w]+)'; my $type_member_func = $type_member . '\(\)'; # Output conversion substitutions. # One for each output format # these are pretty rough my @highlights_man = ( [$type_constant, "\$1"], [$type_constant2, "\$1"], [$type_func, "\\\\fB\$1\\\\fP"], [$type_enum, "\\\\fI\$1\\\\fP"], [$type_struct, "\\\\fI\$1\\\\fP"], [$type_typedef, "\\\\fI\$1\\\\fP"], [$type_union, "\\\\fI\$1\\\\fP"], [$type_param, "\\\\fI\$1\\\\fP"], [$type_member, "\\\\fI\$1\$2\$3\\\\fP"], [$type_fallback, "\\\\fI\$1\\\\fP"] ); my $blankline_man = ""; # rst-mode my @highlights_rst = ( [$type_constant, "``\$1``"], [$type_constant2, "``\$1``"], # Note: need to escape () to avoid func matching later [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"], [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"], [$type_fp_param, "**\$1\\\\(\\\\)**"], [$type_func, "\$1()"], [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"], [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"], [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"], [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"], # in rst this can refer to any type [$type_fallback, "\\:c\\:type\\:`\$1`"], [$type_param, "**\$1**"] ); my $blankline_rst = "\n"; # read arguments if ($#ARGV == -1) { usage(); } my $kernelversion; my $dohighlight = ""; my $verbose = 0; my $output_mode = "rst"; my $output_preformatted = 0; my $no_doc_sections = 0; my $enable_lineno = 0; my @highlights = @highlights_rst; my $blankline = $blankline_rst; 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; # No longer used 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_BODY_MAYBE => 2, # body - or maybe more description STATE_BODY => 3, # the body of the comment STATE_PROTO => 4, # scanning prototype STATE_DOCBLOCK => 5, # documentation block STATE_INLINE => 6, # gathering documentation outside main block }; my $state; my $in_doc_sect; my $leading_space; # 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*(@\s*[\w][\w\.]*\s*):(.*)'; my $doc_inline_end = '^\s*\*/\s*$'; my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\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 = $1; shift @ARGV; if ($cmd eq "man") { $output_mode = "man"; @highlights = @highlights_man; $blankline = $blankline_man; } elsif ($cmd eq "rst") { $output_mode = "rst"; @highlights = @highlights_rst; $blankline = $blankline_rst; } elsif ($cmd eq "none") { $output_mode = "none"; } 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; } 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; # A no-op but don't fail } else { # Unknown argument usage(); } } # continue execution near EOF; # get kernel version from env sub get_kernel_version() { my $version = 'unknown kernel version'; if (defined($ENV{'KERNELVERSION'})) { $version = $ENV{'KERNELVERSION'}; } 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. # sub dump_section { my $file = shift; my $name = shift; my $contents = join "\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 "@\.\.\.") { $name = "..."; $parameterdescs{$name} = $contents; $sectcheck = $sectcheck . $name . " "; $parameterdesc_start_lines{$name} = $new_start_line; $new_start_line = 0; } else { if (defined($sections{$name}) && ($sections{$name} ne "")) { # 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; } } }