GIT 20af653c3fd08bdfed03cef70e5b9d4ec17581e0 git+ssh://master.kernel.org/pub/scm/linux/kernel/git/sam/kbuild.git commit Author: Randy Dunlap Date: Sun Nov 4 12:01:55 2007 -0800 kbuild: add 'includecheck' help text Add 'includecheck' to the Static analyzers help list. Signed-off-by: Randy Dunlap Signed-off-by: Sam Ravnborg commit 7428471269e9109277e4f15f6749ed5bfb1b5731 Author: Johannes Berg Date: Wed Oct 24 15:08:48 2007 -0700 kernel-doc: new P directive for DOC: sections The !P directive includes the contents of a DOC: section given by title, e.g. !Pfilename Title of the section Signed-off-by: Johannes Berg Signed-off-by: Randy Dunlap Signed-off-by: Sam Ravnborg commit 96afb7a14e3c26eddf2403b8499f113dd7790327 Author: Johannes Berg Date: Wed Oct 24 15:08:48 2007 -0700 kernel-doc: use no-doc option When asked by a template to include all functions from a file, it will also include DOC: sections wreaking havoc in the generated docbook file. This patch makes it use the new -no-doc-sections flag for kernel-doc to avoid this. Signed-off-by: Johannes Berg Signed-off-by: Randy Dunlap Signed-off-by: Sam Ravnborg commit 2de76a751339a1a601832f0da4f662d8ca623d63 Author: Johannes Berg Date: Wed Oct 24 15:08:48 2007 -0700 kernel-doc: process functions, not DOC: This flag is necessary for the next patch for docproc to output only the functions and not DOC: sections when a function list is requested. Signed-off-by: Johannes Berg Signed-off-by: Randy Dunlap Signed-off-by: Sam Ravnborg commit 70e19814ede5817d54dd59990be17a488f0eb22c Author: Johannes Berg Date: Wed Oct 24 15:08:48 2007 -0700 kernel-doc: single DOC: selection Currently, DOC: sections are always output even if only a single function is requested, fix this and also make it possible to just output a single DOC: section by giving its title as the function name to output. Also fixes docbook XML well-formedness for sections with examples. Signed-off-by: Johannes Berg Signed-off-by: Randy Dunlap Signed-off-by: Sam Ravnborg commit 5602a717bca11723cd62d3609ca83fb9c599506a Author: Johannes Berg Date: Wed Oct 24 15:08:48 2007 -0700 kernel-doc: init kernel version The kernel-doc script triggers a perl warning when invoked without KERNELVERSION in the environment, rather make it use the string "unknown kernel version" instead. Signed-off-by: Johannes Berg Signed-off-by: Randy Dunlap Signed-off-by: Sam Ravnborg commit b88a38db7969e77bcf2703a23c46a7758fb67b96 Author: Johannes Berg Date: Wed Oct 24 15:08:48 2007 -0700 kernel-doc: fix xml output mode After Randy's patch fixing the HTML output in DOC: sections (6b5b55f6c404fa730a09a8254eb19f5a038afcc2) the same bug remained in XML mode, this fixes it. Signed-off-by: Johannes Berg Signed-off-by: Randy Dunlap Signed-off-by: Sam Ravnborg Makefile | 1 + scripts/basic/docproc.c | 44 +++++++++++++++++++++++- scripts/kernel-doc | 85 ++++++++++++++++++++++++++++++++-------------- 3 files changed, 102 insertions(+), 28 deletions(-) diff --git a/Makefile b/Makefile index e28dde8..81e3f4e 100644 --- a/Makefile +++ b/Makefile @@ -1182,6 +1182,7 @@ help: @echo 'Static analysers' @echo ' checkstack - Generate a list of stack hogs' @echo ' namespacecheck - Name space analysis on compiled kernel' + @echo ' includecheck - Check for duplicate included header files' @echo ' export_report - List the usages of all exported symbols' @if [ -r $(srctree)/include/asm-$(SRCARCH)/Kbuild ]; then \ echo ' headers_check - Sanity check on exported headers'; \ diff --git a/scripts/basic/docproc.c b/scripts/basic/docproc.c index 0e4bd54..35bdc68 100644 --- a/scripts/basic/docproc.c +++ b/scripts/basic/docproc.c @@ -30,6 +30,7 @@ * !Ifilename * !Dfilename * !Ffilename + * !Pfilename * */ @@ -57,6 +58,7 @@ FILEONLY *symbolsonly; typedef void FILELINE(char * file, char * line); FILELINE * singlefunctions; FILELINE * entity_system; +FILELINE * docsection; #define MAXLINESZ 2048 #define MAXFILES 250 @@ -65,6 +67,7 @@ FILELINE * entity_system; #define DOCBOOK "-docbook" #define FUNCTION "-function" #define NOFUNCTION "-nofunction" +#define NODOCSECTIONS "-no-doc-sections" char *srctree; @@ -231,13 +234,14 @@ void docfunctions(char * filename, char * type) for (i=0; i <= symfilecnt; i++) symcnt += symfilelist[i].symbolcnt; - vec = malloc((2 + 2 * symcnt + 2) * sizeof(char*)); + vec = malloc((2 + 2 * symcnt + 3) * sizeof(char *)); if (vec == NULL) { perror("docproc: "); exit(1); } vec[idx++] = KERNELDOC; vec[idx++] = DOCBOOK; + vec[idx++] = NODOCSECTIONS; for (i=0; i < symfilecnt; i++) { struct symfile * sym = &symfilelist[i]; for (j=0; j < sym->symbolcnt; j++) { @@ -287,12 +291,36 @@ void singfunc(char * filename, char * line) } /* + * Insert specific documentation section from a file. + * Call kernel-doc with the following parameters: + * kernel-doc -docbook -function "doc section" filename + */ +void docsect(char *filename, char *line) +{ + char *vec[6]; /* kerneldoc -docbook -function "section" file NULL */ + char *s; + + for (s = line; *s; s++) + if (*s == '\n') + *s = '\0'; + + vec[0] = KERNELDOC; + vec[1] = DOCBOOK; + vec[2] = FUNCTION; + vec[3] = line; + vec[4] = filename; + vec[5] = NULL; + exec_kernel_doc(vec); +} + +/* * Parse file, calling action specific functions for: * 1) Lines containing !E * 2) Lines containing !I * 3) Lines containing !D * 4) Lines containing !F - * 5) Default lines - lines not matching the above + * 5) Lines containing !P + * 6) Default lines - lines not matching the above */ void parse_file(FILE *infile) { @@ -326,6 +354,15 @@ void parse_file(FILE *infile) s++; singlefunctions(line +2, s); break; + case 'P': + /* filename */ + while (*s && !isspace(*s)) s++; + *s++ = '\0'; + /* DOC: section name */ + while (isspace(*s)) + s++; + docsection(line + 2, s); + break; default: defaultline(line); } @@ -372,6 +409,7 @@ int main(int argc, char *argv[]) externalfunctions = find_export_symbols; symbolsonly = find_export_symbols; singlefunctions = noaction2; + docsection = noaction2; parse_file(infile); /* Rewind to start from beginning of file again */ @@ -381,6 +419,7 @@ int main(int argc, char *argv[]) externalfunctions = extfunc; symbolsonly = printline; singlefunctions = singfunc; + docsection = docsect; parse_file(infile); } @@ -394,6 +433,7 @@ int main(int argc, char *argv[]) externalfunctions = adddep; symbolsonly = adddep; singlefunctions = adddep2; + docsection = adddep2; parse_file(infile); printf("\n"); } diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 1d14018..ec54f12 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -46,21 +46,24 @@ use strict; # Note: This only supports 'c'. # usage: -# kernel-doc [ -docbook | -html | -text | -man ] +# kernel-doc [ -docbook | -html | -text | -man ] [ -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 -text or -man. Default is man. # +# -no-doc-sections +# Do not output DOC: sections +# # -function funcname -# If set, then only generate documentation for the given function(s). All -# other functions are ignored. +# 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). -# Cannot be used together with -function -# (yes, that's a bug -- perl hackers can fix it 8)) +# 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 # @@ -182,10 +185,10 @@ my $blankline_html = $local_lt . "p" . $local_gt; # was "

" my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2", $type_constant, "\$1", $type_func, "\$1", - $type_struct, "\$1", + $type_struct_xml, "\$1", $type_env, "\$1", $type_param, "\$1" ); -my $blankline_xml = "\n"; +my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n"; # gnome, docbook format my %highlights_gnome = ( $type_constant, "\$1", @@ -211,7 +214,7 @@ my $blankline_text = ""; sub usage { - print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ]\n"; + print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ] [ -no-doc-sections ]\n"; print " [ -function funcname [ -function funcname ...] ]\n"; print " [ -nofunction funcname [ -nofunction funcname ...] ]\n"; print " c source file(s) > outputfile\n"; @@ -225,6 +228,7 @@ if ($#ARGV==-1) { my $verbose = 0; my $output_mode = "man"; +my $no_doc_sections = 0; my %highlights = %highlights_man; my $blankline = $blankline_man; my $modulename = "Kernel API"; @@ -329,12 +333,14 @@ while ($ARGV[0] =~ m/^-(.*)/) { usage(); } elsif ($cmd eq '-filelist') { $filelist = shift @ARGV; + } elsif ($cmd eq '-no-doc-sections') { + $no_doc_sections = 1; } } # get kernel version from env sub get_kernel_version() { - my $version; + my $version = 'unknown kernel version'; if (defined($ENV{'KERNELVERSION'})) { $version = $ENV{'KERNELVERSION'}; @@ -374,6 +380,29 @@ sub dump_section { } ## +# dump DOC: section after checking that it should go out +# +sub dump_doc_section { + 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 $name, $contents; + output_blockhead({'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'module' => $modulename, + 'content-only' => ($function_only != 0), }); + } +} + +## # output function # # parameterdescs, a hash. @@ -394,7 +423,7 @@ sub output_highlight { # confess "output_highlight got called with no args?\n"; # } - if ($output_mode eq "html") { + if ($output_mode eq "html" || $output_mode eq "xml") { $contents = local_unescape($contents); # convert data read & converted thru xml_escape() into &xyz; format: $contents =~ s/\\\\\\/&/g; @@ -564,8 +593,8 @@ sub output_function_html(%) { print "

\n"; } -# output intro in html -sub output_intro_html(%) { +# output DOC: block header in html +sub output_blockhead_html(%) { my %args = %{$_[0]}; my ($parameter, $section); my $count; @@ -871,7 +900,7 @@ sub output_typedef_xml(%) { } # output in XML DocBook -sub output_intro_xml(%) { +sub output_blockhead_xml(%) { my %args = %{$_[0]}; my ($parameter, $section); my $count; @@ -882,15 +911,23 @@ sub output_intro_xml(%) { # print out each section $lineprefix=" "; foreach $section (@{$args{'sectionlist'}}) { - print "\n $section\n \n"; + if (!$args{'content-only'}) { + print "\n $section\n"; + } if ($section =~ m/EXAMPLE/i) { print "\n"; + } else { + print "\n"; } output_highlight($args{'sections'}{$section}); if ($section =~ m/EXAMPLE/i) { print "\n"; + } else { + print ""; + } + if (!$args{'content-only'}) { + print "\n\n"; } - print " \n\n"; } print "\n\n"; @@ -1137,7 +1174,7 @@ sub output_typedef_man(%) { } } -sub output_intro_man(%) { +sub output_blockhead_man(%) { my %args = %{$_[0]}; my ($parameter, $section); my $count; @@ -1294,7 +1331,7 @@ sub output_struct_text(%) { output_section_text(@_); } -sub output_intro_text(%) { +sub output_blockhead_text(%) { my %args = %{$_[0]}; my ($parameter, $section); @@ -1325,9 +1362,9 @@ sub output_declaration { ## # generic output function - calls the right one based on current output mode. -sub output_intro { +sub output_blockhead { no strict 'refs'; - my $func = "output_intro_".$output_mode; + my $func = "output_blockhead_".$output_mode; &$func(@_); $section_counter++; } @@ -1926,9 +1963,7 @@ sub process_file($) { } elsif ($state == 4) { # Documentation block if (/$doc_block/) { - dump_section($section, xml_escape($contents)); - output_intro({'sectionlist' => \@sectionlist, - 'sections' => \%sections }); + dump_doc_section($section, xml_escape($contents)); $contents = ""; $function = ""; %constants = (); @@ -1946,9 +1981,7 @@ sub process_file($) { } elsif (/$doc_end/) { - dump_section($section, xml_escape($contents)); - output_intro({'sectionlist' => \@sectionlist, - 'sections' => \%sections }); + dump_doc_section($section, xml_escape($contents)); $contents = ""; $function = ""; %constants = ();