diff --git a/doc/DocBook/.gitignore b/doc/DocBook/.gitignore index 90c1b112a1..720f245ceb 100644 --- a/doc/DocBook/.gitignore +++ b/doc/DocBook/.gitignore @@ -1,4 +1,3 @@ -*/ *.xml *.ps *.pdf diff --git a/doc/DocBook/stylesheet.xsl b/doc/DocBook/stylesheet.xsl index 8adce568b6..85b2527519 100644 --- a/doc/DocBook/stylesheet.xsl +++ b/doc/DocBook/stylesheet.xsl @@ -7,5 +7,4 @@ 2 1 -../docbook.css diff --git a/scripts/docproc.c b/scripts/docproc.c index 23c3a434b2..2b69eaf5b6 100644 --- a/scripts/docproc.c +++ b/scripts/docproc.c @@ -72,6 +72,7 @@ FILELINE * docsection; #define FUNCTION "-function" #define NOFUNCTION "-nofunction" #define NODOCSECTIONS "-no-doc-sections" +#define SHOWNOTFOUND "-show-not-found" static char *srctree, *kernsrctree; @@ -153,7 +154,7 @@ int symfilecnt = 0; static void add_new_symbol(struct symfile *sym, char * symname) { sym->symbollist = - realloc(sym->symbollist, (sym->symbolcnt + 1) * sizeof(char *)); + realloc(sym->symbollist, (sym->symbolcnt + 1) * sizeof(char *)); sym->symbollist[sym->symbolcnt++].name = strdup(symname); } @@ -214,7 +215,7 @@ static void find_export_symbols(char * filename) char *p; char *e; if (((p = strstr(line, "EXPORT_SYMBOL_GPL")) != NULL) || - ((p = strstr(line, "EXPORT_SYMBOL")) != NULL)) { + ((p = strstr(line, "EXPORT_SYMBOL")) != NULL)) { /* Skip EXPORT_SYMBOL{_GPL} */ while (isalnum(*p) || *p == '_') p++; @@ -290,27 +291,28 @@ static void extfunc(char * filename) { docfunctions(filename, FUNCTION); } static void singfunc(char * filename, char * line) { char *vec[200]; /* Enough for specific functions */ - int i, idx = 0; - int startofsym = 1; + int i, idx = 0; + int startofsym = 1; vec[idx++] = KERNELDOC; vec[idx++] = DOCBOOK; + vec[idx++] = SHOWNOTFOUND; - /* Split line up in individual parameters preceded by FUNCTION */ - for (i=0; line[i]; i++) { - if (isspace(line[i])) { - line[i] = '\0'; - startofsym = 1; - continue; - } - if (startofsym) { - startofsym = 0; - vec[idx++] = FUNCTION; - vec[idx++] = &line[i]; - } - } + /* Split line up in individual parameters preceded by FUNCTION */ + for (i=0; line[i]; i++) { + if (isspace(line[i])) { + line[i] = '\0'; + startofsym = 1; + continue; + } + if (startofsym) { + startofsym = 0; + vec[idx++] = FUNCTION; + vec[idx++] = &line[i]; + } + } for (i = 0; i < idx; i++) { - if (strcmp(vec[i], FUNCTION)) - continue; + if (strcmp(vec[i], FUNCTION)) + continue; consume_symbol(vec[i + 1]); } vec[idx++] = filename; @@ -325,7 +327,8 @@ static void singfunc(char * filename, char * line) */ static void docsect(char *filename, char *line) { - char *vec[6]; /* kerneldoc -docbook -function "section" file NULL */ + /* kerneldoc -docbook -show-not-found -function "section" file NULL */ + char *vec[7]; char *s; for (s = line; *s; s++) @@ -341,10 +344,11 @@ static void docsect(char *filename, char *line) vec[0] = KERNELDOC; vec[1] = DOCBOOK; - vec[2] = FUNCTION; - vec[3] = line; - vec[4] = filename; - vec[5] = NULL; + vec[2] = SHOWNOTFOUND; + vec[3] = FUNCTION; + vec[4] = line; + vec[5] = filename; + vec[6] = NULL; exec_kernel_doc(vec); } @@ -456,14 +460,14 @@ static void parse_file(FILE *infile) break; case 'D': while (*s && !isspace(*s)) s++; - *s = '\0'; - symbolsonly(line+2); - break; + *s = '\0'; + symbolsonly(line+2); + break; case 'F': /* filename */ while (*s && !isspace(*s)) s++; *s++ = '\0'; - /* function names */ + /* function names */ while (isspace(*s)) s++; singlefunctions(line +2, s); @@ -511,11 +515,11 @@ int main(int argc, char *argv[]) } /* Open file, exit on error */ infile = fopen(argv[2], "r"); - if (infile == NULL) { - fprintf(stderr, "docproc: "); - perror(argv[2]); - exit(2); - } + if (infile == NULL) { + fprintf(stderr, "docproc: "); + perror(argv[2]); + exit(2); + } if (strcmp("doc", argv[1]) == 0) { /* Need to do this in two passes. diff --git a/scripts/kernel-doc b/scripts/kernel-doc index cbbf34c27c..ba2bafd687 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -137,6 +137,8 @@ use strict; # 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. # @@ -245,6 +247,7 @@ 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; @@ -254,6 +257,7 @@ my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December')[(localtime)[4]] . " " . ((localtime)[5]+1900); +my $show_not_found = 0; # Essentially these are globals. # They probably want to be tidied up, made more localised or something. @@ -295,9 +299,10 @@ 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 . '(.*)'; +my $doc_content = $doc_com_body . '(.*)'; my $doc_block = $doc_com . 'DOC:\s*(.*)?'; my %constants; @@ -313,6 +318,7 @@ 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 --"; @@ -364,6 +370,8 @@ while ($ARGV[0] =~ m/^-(.*)/) { usage(); } elsif ($cmd eq '-no-doc-sections') { $no_doc_sections = 1; + } elsif ($cmd eq '-show-not-found') { + $show_not_found = 1; } } @@ -432,7 +440,7 @@ sub dump_doc_section { my $contents = join "\n", @_; if ($no_doc_sections) { - return; + return; } if (($function_only == 0) || @@ -485,8 +493,13 @@ sub output_highlight { $contents =~ s/\s+$//; } foreach $line (split "\n", $contents) { + if (! $output_preformatted) { + $line =~ s/^\s*//; + } if ($line eq ""){ - print $lineprefix, local_unescape($blankline); + if (! $output_preformatted) { + print $lineprefix, local_unescape($blankline); + } } else { $line =~ s/\\\\\\/\&/g; if ($output_mode eq "man" && substr($line, 0, 1) eq ".") { @@ -902,10 +915,12 @@ sub output_section_xml(%) { print "$section\n"; if ($section =~ m/EXAMPLE/i) { print "\n"; + $output_preformatted = 1; } else { print "\n"; } output_highlight($args{'sections'}{$section}); + $output_preformatted = 0; if ($section =~ m/EXAMPLE/i) { print "\n"; } else { @@ -1208,10 +1223,12 @@ sub output_blockhead_xml(%) { } if ($section =~ m/EXAMPLE/i) { print "\n"; + $output_preformatted = 1; } else { print "\n"; } output_highlight($args{'sections'}{$section}); + $output_preformatted = 0; if ($section =~ m/EXAMPLE/i) { print "\n"; } else { @@ -1287,10 +1304,12 @@ sub output_function_gnome { print "\n $section\n"; if ($section =~ m/EXAMPLE/i) { print "\n"; + $output_preformatted = 1; } else { } print "\n"; output_highlight($args{'sections'}{$section}); + $output_preformatted = 0; print "\n"; if ($section =~ m/EXAMPLE/i) { print "\n"; @@ -1734,7 +1753,7 @@ sub dump_struct($$) { # strip kmemcheck_bitfield_{begin,end}.*; $members =~ s/kmemcheck_bitfield_.*?;//gos; # strip attributes - $members =~ s/__aligned\s*\(\d+\)//gos; + $members =~ s/__aligned\s*\(.+\)//gos; create_parameterlist($members, ';', $file); check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested); @@ -2025,6 +2044,28 @@ sub check_sections($$$$$$) { } } +## +# Checks the section describing the return value of a function. +sub check_return_section { + my $file = shift; + my $declaration_name = shift; + my $return_type = shift; + + # Ignore an empty return type (It's a macro) + # Ignore functions with a "void" return type. (But don't ignore "void *") + if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) { + return; + } + + if (!defined($sections{$section_return}) || + $sections{$section_return} eq "") { + print STDERR "Warning(${file}:$.): " . + "No description found for return value of " . + "'$declaration_name'\n"; + ++$warnings; + } +} + ## # takes a function prototype and the name of the current file being # processed and spits out all the details stored in the global @@ -2041,7 +2082,6 @@ sub dump_function($$) { $prototype =~ s/^__inline +//; $prototype =~ s/^__always_inline +//; $prototype =~ s/^noinline +//; - $prototype =~ s/__devinit +//; $prototype =~ s/__init +//; $prototype =~ s/__init_or_module +//; $prototype =~ s/__must_check +//; @@ -2088,14 +2128,22 @@ sub dump_function($$) { create_parameterlist($args, ',', $file); } else { - print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n"; - ++$errors; + print STDERR "Warning(${file}:$.): cannot understand function prototype: '$prototype'\n"; return; } my $prms = join " ", @parameterlist; check_sections($file, $declaration_name, "function", $sectcheck, $prms, ""); + # This check emits a lot of warnings at the moment, because many + # functions don't have a 'Return' doc section. So until the number + # of warnings goes sufficiently down, the check is only performed in + # verbose mode. + # TODO: always perform the check. + if ($verbose) { + check_return_section($file, $declaration_name, $return_type); + } + output_declaration($declaration_name, 'function', {'function' => $declaration_name, @@ -2305,6 +2353,9 @@ sub process_file($) { $section_counter = 0; while () { + while (s/\\\s*$//) { + $_ .= ; + } if ($state == 0) { if (/$doc_start/o) { $state = 1; # next line is always the function name @@ -2332,7 +2383,7 @@ sub process_file($) { $descr= $1; $descr =~ s/^\s*//; $descr =~ s/\s*$//; - $descr =~ s/\s+/ /; + $descr =~ s/\s+/ /g; $declaration_purpose = xml_escape($descr); $in_purpose = 1; } else { @@ -2424,9 +2475,7 @@ sub process_file($) { # Continued declaration purpose chomp($declaration_purpose); $declaration_purpose .= " " . xml_escape($1); - } elsif ($section =~ m/^Example/) { - $_ =~ s/^\s*\*//; - $contents .= $_; + $declaration_purpose =~ s/\s+/ /g; } else { $contents .= $1 . "\n"; } @@ -2489,6 +2538,9 @@ sub process_file($) { } if ($initial_section_counter == $section_counter) { print STDERR "Warning(${file}): no structured comments found\n"; + if (($function_only == 1) && ($show_not_found == 1)) { + print STDERR " Was looking for '$_'.\n" for keys %function_table; + } if ($output_mode eq "xml") { # The template wants at least one RefEntry here; make one. print "\n";