#!/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):  -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. 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 = '\\&amp;((struct\s*)*[_\w]+)';my $type_env = '(\$\w+)';my $type_enum_full = '\&(enum)\s*([_\w]+)';my $type_struct_full = '\&(struct)\s*([_\w]+)'; # 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``"],                       [$type_func, "\\:c\\:func\\:`\$1`"],                       [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],                       [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],                       [$type_struct, "\\:c\\:type\\:`struct \$1 <\$1>`"],                       [$type_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 @highlights = @highlights_man;my $blankline = $blankline_man;my $modulename = "Kernel API";my $function_only = 0;my $show_not_found = 0; 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 ($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=""; # states# 0 - normal code# 1 - looking for function name# 2 - scanning field start.# 3 - scanning prototype.# 4 - documentation block# 5 - gathering documentation outside main blockmy $state;my $in_doc_sect; # Split Doc State# 0 - Invalid (Before start or after finish)# 1 - Is started (the /** was found inside a struct)# 2 - The @parameter header was found, start accepting multi paragraph text.# 3 - Finished (the */ was found)# 4 - Error - Comment without header was found. Spit a warning as it's not#     proper kernel-doc and ignore the rest.my $split_doc_state; #declaration types: can be# 'function', 'struct', 'union', 'enum', 'typedef'my $decl_type; my $doc_special = "\@\%\$\&"; my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.my $doc_end = '\*/';my $doc_com = '\s*\*\s*';my $doc_com_body = '\s*\* ?';my $doc_decl = $doc_com . '(\w+)';my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';my $doc_content = $doc_com_body . '(.*)';my $doc_block = $doc_com . 'DOC:\s*(.*)?';my $doc_split_start = '^\s*/\*\*\s*$';my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)';my $doc_split_end = '^\s*\*/\s*$'; my %constants;my %parameterdescs;my @parameterlist;my %sections;my @sectionlist;my $sectcheck;my $struct_actual; my $contents = "";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	$function_only = 1;	$function = shift @ARGV;	$function_table{$function} = 1;    } elsif ($cmd eq "-nofunction") { # to only output specific functions	$function_only = 2;	$function = shift @ARGV;	$function_table{$function} = 1;    } 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 '-show-not-found') {	$show_not_found = 1;    }} # 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;} ### 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_constant/) {	$name = $1;#	print STDERR "constant section '$1' = '$contents'\n";	$constants{$name} = $contents;    } elsif ($name =~ m/$type_param/) {#	print STDERR "parameter def '$1' = '$contents'\n";	$name = $1;	$parameterdescs{$name} = $contents;	$sectcheck = $sectcheck . $name . " ";    } elsif ($name eq "@\.\.\.") {#	print STDERR "parameter def '...' = '$contents'\n";	$name = "...";	$parameterdescs{$name} = $contents;	$sectcheck = $sectcheck . $name . " ";    } else {#	print STDERR "other section '$name' = '$contents'\n";	if (defined($sections{$name}) && ($sections{$name} ne "")) {		print STDERR "${file}:$.: error: duplicate section name '$name'\n";		++$errors;	}	$sections{$name} = $contents;	push @sectionlist, $name;    }

Lines 1–500 of 2971. Load more