#!/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> ## This will read a 'c' file and scan for embedded comments in the# style of gnome comments (+minor extensions - see below).# # Note: This only supports 'c'. # usage:# kernel-doc [ -docbook | -html | -html5 | -text | -man | -list ]#            [ -no-doc-sections ]#            [ -function funcname [ -function funcname ...] ]#            c file(s)s > outputfile# or#            [ -nofunction funcname [ -function funcname ...] ]#            c file(s)s > outputfile##  Set output format using one of -docbook -html -html5 -text or -man.#  Default is man.#  The -list format is for internal use by docproc.##  -no-doc-sections#	Do not output DOC: sections##  -function funcname#	If set, then only generate documentation for the given function(s) or#	DOC: section titles.  All other functions and DOC: sections are ignored.##  -nofunction funcname#	If set, then only generate documentation for the other function(s)/DOC:#	sections. Cannot be used together with -function (yes, that's a bug --#	perl hackers can fix it 8))##  c files - list of 'c' files to process##  All output goes to stdout, with errors to stderr. ## 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+)'; # 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_func, "<function>\$1</function>",			$type_struct_xml, "<structname>\$1</structname>",			$type_env, "<envar>\$1</envar>",			$type_param, "<parameter>\$1</parameter>" );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 = ""; # 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 "-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; sub usage {    print "Usage: $0 [ -docbook | -html | -html5 | -text | -man | -list ]\n";    print "         [ -no-doc-sections ]\n";    print "         [ -function funcname [ -function funcname ...] ]\n";    print "         [ -nofunction funcname [ -nofunction funcname ...] ]\n";    print "         [ -v ]\n";    print "         c source file(s) > outputfile\n";    print "         -v : verbose output, more warnings & other info listed\n";    exit 1;} # 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;    }} ### dump DOC: section after checking that it should go out#sub dump_doc_section {    my $file = shift;    my $name = shift;    my $contents = join "\n", @_;     if ($no_doc_sections) {        return;    }     if (($function_only == 0) ||	( $function_only == 1 && defined($function_table{$name})) ||	( $function_only == 2 && !defined($function_table{$name})))    {	dump_section($file, $name, $contents);	output_blockhead({'sectionlist' => \@sectionlist,			  'sections' => \%sections,			  'module' => $modulename,			  'content-only' => ($function_only != 0), });

Lines 1–500 of 2703. Load more