Commit ced032989a1b26851bc567df70199031dab37f19
Committed by
Tom Rini
1 parent
8fac9c7b7d
Exists in
master
and in
49 other branches
kernel-doc: update kernel-doc related files to Linux v3.13
Signed-off-by: Masahiro Yamada <yamada.m@jp.panasonic.com> Acked-by: Simon Glass <sjg@chromium.org>
Showing 4 changed files with 101 additions and 47 deletions Side-by-side Diff
doc/DocBook/.gitignore
doc/DocBook/stylesheet.xsl
scripts/docproc.c
... | ... | @@ -72,6 +72,7 @@ |
72 | 72 | #define FUNCTION "-function" |
73 | 73 | #define NOFUNCTION "-nofunction" |
74 | 74 | #define NODOCSECTIONS "-no-doc-sections" |
75 | +#define SHOWNOTFOUND "-show-not-found" | |
75 | 76 | |
76 | 77 | static char *srctree, *kernsrctree; |
77 | 78 | |
... | ... | @@ -153,7 +154,7 @@ |
153 | 154 | static void add_new_symbol(struct symfile *sym, char * symname) |
154 | 155 | { |
155 | 156 | sym->symbollist = |
156 | - realloc(sym->symbollist, (sym->symbolcnt + 1) * sizeof(char *)); | |
157 | + realloc(sym->symbollist, (sym->symbolcnt + 1) * sizeof(char *)); | |
157 | 158 | sym->symbollist[sym->symbolcnt++].name = strdup(symname); |
158 | 159 | } |
159 | 160 | |
... | ... | @@ -214,7 +215,7 @@ |
214 | 215 | char *p; |
215 | 216 | char *e; |
216 | 217 | if (((p = strstr(line, "EXPORT_SYMBOL_GPL")) != NULL) || |
217 | - ((p = strstr(line, "EXPORT_SYMBOL")) != NULL)) { | |
218 | + ((p = strstr(line, "EXPORT_SYMBOL")) != NULL)) { | |
218 | 219 | /* Skip EXPORT_SYMBOL{_GPL} */ |
219 | 220 | while (isalnum(*p) || *p == '_') |
220 | 221 | p++; |
221 | 222 | |
222 | 223 | |
223 | 224 | |
... | ... | @@ -290,27 +291,28 @@ |
290 | 291 | static void singfunc(char * filename, char * line) |
291 | 292 | { |
292 | 293 | char *vec[200]; /* Enough for specific functions */ |
293 | - int i, idx = 0; | |
294 | - int startofsym = 1; | |
294 | + int i, idx = 0; | |
295 | + int startofsym = 1; | |
295 | 296 | vec[idx++] = KERNELDOC; |
296 | 297 | vec[idx++] = DOCBOOK; |
298 | + vec[idx++] = SHOWNOTFOUND; | |
297 | 299 | |
298 | - /* Split line up in individual parameters preceded by FUNCTION */ | |
299 | - for (i=0; line[i]; i++) { | |
300 | - if (isspace(line[i])) { | |
301 | - line[i] = '\0'; | |
302 | - startofsym = 1; | |
303 | - continue; | |
304 | - } | |
305 | - if (startofsym) { | |
306 | - startofsym = 0; | |
307 | - vec[idx++] = FUNCTION; | |
308 | - vec[idx++] = &line[i]; | |
309 | - } | |
310 | - } | |
300 | + /* Split line up in individual parameters preceded by FUNCTION */ | |
301 | + for (i=0; line[i]; i++) { | |
302 | + if (isspace(line[i])) { | |
303 | + line[i] = '\0'; | |
304 | + startofsym = 1; | |
305 | + continue; | |
306 | + } | |
307 | + if (startofsym) { | |
308 | + startofsym = 0; | |
309 | + vec[idx++] = FUNCTION; | |
310 | + vec[idx++] = &line[i]; | |
311 | + } | |
312 | + } | |
311 | 313 | for (i = 0; i < idx; i++) { |
312 | - if (strcmp(vec[i], FUNCTION)) | |
313 | - continue; | |
314 | + if (strcmp(vec[i], FUNCTION)) | |
315 | + continue; | |
314 | 316 | consume_symbol(vec[i + 1]); |
315 | 317 | } |
316 | 318 | vec[idx++] = filename; |
... | ... | @@ -325,7 +327,8 @@ |
325 | 327 | */ |
326 | 328 | static void docsect(char *filename, char *line) |
327 | 329 | { |
328 | - char *vec[6]; /* kerneldoc -docbook -function "section" file NULL */ | |
330 | + /* kerneldoc -docbook -show-not-found -function "section" file NULL */ | |
331 | + char *vec[7]; | |
329 | 332 | char *s; |
330 | 333 | |
331 | 334 | for (s = line; *s; s++) |
... | ... | @@ -341,10 +344,11 @@ |
341 | 344 | |
342 | 345 | vec[0] = KERNELDOC; |
343 | 346 | vec[1] = DOCBOOK; |
344 | - vec[2] = FUNCTION; | |
345 | - vec[3] = line; | |
346 | - vec[4] = filename; | |
347 | - vec[5] = NULL; | |
347 | + vec[2] = SHOWNOTFOUND; | |
348 | + vec[3] = FUNCTION; | |
349 | + vec[4] = line; | |
350 | + vec[5] = filename; | |
351 | + vec[6] = NULL; | |
348 | 352 | exec_kernel_doc(vec); |
349 | 353 | } |
350 | 354 | |
351 | 355 | |
... | ... | @@ -456,14 +460,14 @@ |
456 | 460 | break; |
457 | 461 | case 'D': |
458 | 462 | while (*s && !isspace(*s)) s++; |
459 | - *s = '\0'; | |
460 | - symbolsonly(line+2); | |
461 | - break; | |
463 | + *s = '\0'; | |
464 | + symbolsonly(line+2); | |
465 | + break; | |
462 | 466 | case 'F': |
463 | 467 | /* filename */ |
464 | 468 | while (*s && !isspace(*s)) s++; |
465 | 469 | *s++ = '\0'; |
466 | - /* function names */ | |
470 | + /* function names */ | |
467 | 471 | while (isspace(*s)) |
468 | 472 | s++; |
469 | 473 | singlefunctions(line +2, s); |
... | ... | @@ -511,11 +515,11 @@ |
511 | 515 | } |
512 | 516 | /* Open file, exit on error */ |
513 | 517 | infile = fopen(argv[2], "r"); |
514 | - if (infile == NULL) { | |
515 | - fprintf(stderr, "docproc: "); | |
516 | - perror(argv[2]); | |
517 | - exit(2); | |
518 | - } | |
518 | + if (infile == NULL) { | |
519 | + fprintf(stderr, "docproc: "); | |
520 | + perror(argv[2]); | |
521 | + exit(2); | |
522 | + } | |
519 | 523 | |
520 | 524 | if (strcmp("doc", argv[1]) == 0) { |
521 | 525 | /* Need to do this in two passes. |
scripts/kernel-doc
... | ... | @@ -137,6 +137,8 @@ |
137 | 137 | # should document the "Context:" of the function, e.g. whether the functions |
138 | 138 | # can be called form interrupts. Unlike other sections you can end it with an |
139 | 139 | # empty line. |
140 | +# A non-void function should have a "Return:" section describing the return | |
141 | +# value(s). | |
140 | 142 | # Example-sections should contain the string EXAMPLE so that they are marked |
141 | 143 | # appropriately in DocBook. |
142 | 144 | # |
... | ... | @@ -245,6 +247,7 @@ |
245 | 247 | |
246 | 248 | my $verbose = 0; |
247 | 249 | my $output_mode = "man"; |
250 | +my $output_preformatted = 0; | |
248 | 251 | my $no_doc_sections = 0; |
249 | 252 | my %highlights = %highlights_man; |
250 | 253 | my $blankline = $blankline_man; |
... | ... | @@ -254,6 +257,7 @@ |
254 | 257 | 'July', 'August', 'September', 'October', |
255 | 258 | 'November', 'December')[(localtime)[4]] . |
256 | 259 | " " . ((localtime)[5]+1900); |
260 | +my $show_not_found = 0; | |
257 | 261 | |
258 | 262 | # Essentially these are globals. |
259 | 263 | # They probably want to be tidied up, made more localised or something. |
260 | 264 | |
... | ... | @@ -295,9 +299,10 @@ |
295 | 299 | my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start. |
296 | 300 | my $doc_end = '\*/'; |
297 | 301 | my $doc_com = '\s*\*\s*'; |
302 | +my $doc_com_body = '\s*\* ?'; | |
298 | 303 | my $doc_decl = $doc_com . '(\w+)'; |
299 | 304 | my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)'; |
300 | -my $doc_content = $doc_com . '(.*)'; | |
305 | +my $doc_content = $doc_com_body . '(.*)'; | |
301 | 306 | my $doc_block = $doc_com . 'DOC:\s*(.*)?'; |
302 | 307 | |
303 | 308 | my %constants; |
... | ... | @@ -313,6 +318,7 @@ |
313 | 318 | my $section_intro = "Introduction"; |
314 | 319 | my $section = $section_default; |
315 | 320 | my $section_context = "Context"; |
321 | +my $section_return = "Return"; | |
316 | 322 | |
317 | 323 | my $undescribed = "-- undescribed --"; |
318 | 324 | |
... | ... | @@ -364,6 +370,8 @@ |
364 | 370 | usage(); |
365 | 371 | } elsif ($cmd eq '-no-doc-sections') { |
366 | 372 | $no_doc_sections = 1; |
373 | + } elsif ($cmd eq '-show-not-found') { | |
374 | + $show_not_found = 1; | |
367 | 375 | } |
368 | 376 | } |
369 | 377 | |
... | ... | @@ -432,7 +440,7 @@ |
432 | 440 | my $contents = join "\n", @_; |
433 | 441 | |
434 | 442 | if ($no_doc_sections) { |
435 | - return; | |
443 | + return; | |
436 | 444 | } |
437 | 445 | |
438 | 446 | if (($function_only == 0) || |
439 | 447 | |
... | ... | @@ -485,8 +493,13 @@ |
485 | 493 | $contents =~ s/\s+$//; |
486 | 494 | } |
487 | 495 | foreach $line (split "\n", $contents) { |
496 | + if (! $output_preformatted) { | |
497 | + $line =~ s/^\s*//; | |
498 | + } | |
488 | 499 | if ($line eq ""){ |
489 | - print $lineprefix, local_unescape($blankline); | |
500 | + if (! $output_preformatted) { | |
501 | + print $lineprefix, local_unescape($blankline); | |
502 | + } | |
490 | 503 | } else { |
491 | 504 | $line =~ s/\\\\\\/\&/g; |
492 | 505 | if ($output_mode eq "man" && substr($line, 0, 1) eq ".") { |
493 | 506 | |
... | ... | @@ -902,10 +915,12 @@ |
902 | 915 | print "<title>$section</title>\n"; |
903 | 916 | if ($section =~ m/EXAMPLE/i) { |
904 | 917 | print "<informalexample><programlisting>\n"; |
918 | + $output_preformatted = 1; | |
905 | 919 | } else { |
906 | 920 | print "<para>\n"; |
907 | 921 | } |
908 | 922 | output_highlight($args{'sections'}{$section}); |
923 | + $output_preformatted = 0; | |
909 | 924 | if ($section =~ m/EXAMPLE/i) { |
910 | 925 | print "</programlisting></informalexample>\n"; |
911 | 926 | } else { |
912 | 927 | |
... | ... | @@ -1208,10 +1223,12 @@ |
1208 | 1223 | } |
1209 | 1224 | if ($section =~ m/EXAMPLE/i) { |
1210 | 1225 | print "<example><para>\n"; |
1226 | + $output_preformatted = 1; | |
1211 | 1227 | } else { |
1212 | 1228 | print "<para>\n"; |
1213 | 1229 | } |
1214 | 1230 | output_highlight($args{'sections'}{$section}); |
1231 | + $output_preformatted = 0; | |
1215 | 1232 | if ($section =~ m/EXAMPLE/i) { |
1216 | 1233 | print "</para></example>\n"; |
1217 | 1234 | } else { |
1218 | 1235 | |
... | ... | @@ -1287,10 +1304,12 @@ |
1287 | 1304 | print "<simplesect>\n <title>$section</title>\n"; |
1288 | 1305 | if ($section =~ m/EXAMPLE/i) { |
1289 | 1306 | print "<example><programlisting>\n"; |
1307 | + $output_preformatted = 1; | |
1290 | 1308 | } else { |
1291 | 1309 | } |
1292 | 1310 | print "<para>\n"; |
1293 | 1311 | output_highlight($args{'sections'}{$section}); |
1312 | + $output_preformatted = 0; | |
1294 | 1313 | print "</para>\n"; |
1295 | 1314 | if ($section =~ m/EXAMPLE/i) { |
1296 | 1315 | print "</programlisting></example>\n"; |
... | ... | @@ -1734,7 +1753,7 @@ |
1734 | 1753 | # strip kmemcheck_bitfield_{begin,end}.*; |
1735 | 1754 | $members =~ s/kmemcheck_bitfield_.*?;//gos; |
1736 | 1755 | # strip attributes |
1737 | - $members =~ s/__aligned\s*\(\d+\)//gos; | |
1756 | + $members =~ s/__aligned\s*\(.+\)//gos; | |
1738 | 1757 | |
1739 | 1758 | create_parameterlist($members, ';', $file); |
1740 | 1759 | check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested); |
... | ... | @@ -2026,6 +2045,28 @@ |
2026 | 2045 | } |
2027 | 2046 | |
2028 | 2047 | ## |
2048 | +# Checks the section describing the return value of a function. | |
2049 | +sub check_return_section { | |
2050 | + my $file = shift; | |
2051 | + my $declaration_name = shift; | |
2052 | + my $return_type = shift; | |
2053 | + | |
2054 | + # Ignore an empty return type (It's a macro) | |
2055 | + # Ignore functions with a "void" return type. (But don't ignore "void *") | |
2056 | + if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) { | |
2057 | + return; | |
2058 | + } | |
2059 | + | |
2060 | + if (!defined($sections{$section_return}) || | |
2061 | + $sections{$section_return} eq "") { | |
2062 | + print STDERR "Warning(${file}:$.): " . | |
2063 | + "No description found for return value of " . | |
2064 | + "'$declaration_name'\n"; | |
2065 | + ++$warnings; | |
2066 | + } | |
2067 | +} | |
2068 | + | |
2069 | +## | |
2029 | 2070 | # takes a function prototype and the name of the current file being |
2030 | 2071 | # processed and spits out all the details stored in the global |
2031 | 2072 | # arrays/hashes. |
... | ... | @@ -2041,7 +2082,6 @@ |
2041 | 2082 | $prototype =~ s/^__inline +//; |
2042 | 2083 | $prototype =~ s/^__always_inline +//; |
2043 | 2084 | $prototype =~ s/^noinline +//; |
2044 | - $prototype =~ s/__devinit +//; | |
2045 | 2085 | $prototype =~ s/__init +//; |
2046 | 2086 | $prototype =~ s/__init_or_module +//; |
2047 | 2087 | $prototype =~ s/__must_check +//; |
2048 | 2088 | |
... | ... | @@ -2088,14 +2128,22 @@ |
2088 | 2128 | |
2089 | 2129 | create_parameterlist($args, ',', $file); |
2090 | 2130 | } else { |
2091 | - print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n"; | |
2092 | - ++$errors; | |
2131 | + print STDERR "Warning(${file}:$.): cannot understand function prototype: '$prototype'\n"; | |
2093 | 2132 | return; |
2094 | 2133 | } |
2095 | 2134 | |
2096 | 2135 | my $prms = join " ", @parameterlist; |
2097 | 2136 | check_sections($file, $declaration_name, "function", $sectcheck, $prms, ""); |
2098 | 2137 | |
2138 | + # This check emits a lot of warnings at the moment, because many | |
2139 | + # functions don't have a 'Return' doc section. So until the number | |
2140 | + # of warnings goes sufficiently down, the check is only performed in | |
2141 | + # verbose mode. | |
2142 | + # TODO: always perform the check. | |
2143 | + if ($verbose) { | |
2144 | + check_return_section($file, $declaration_name, $return_type); | |
2145 | + } | |
2146 | + | |
2099 | 2147 | output_declaration($declaration_name, |
2100 | 2148 | 'function', |
2101 | 2149 | {'function' => $declaration_name, |
... | ... | @@ -2305,6 +2353,9 @@ |
2305 | 2353 | |
2306 | 2354 | $section_counter = 0; |
2307 | 2355 | while (<IN>) { |
2356 | + while (s/\\\s*$//) { | |
2357 | + $_ .= <IN>; | |
2358 | + } | |
2308 | 2359 | if ($state == 0) { |
2309 | 2360 | if (/$doc_start/o) { |
2310 | 2361 | $state = 1; # next line is always the function name |
... | ... | @@ -2332,7 +2383,7 @@ |
2332 | 2383 | $descr= $1; |
2333 | 2384 | $descr =~ s/^\s*//; |
2334 | 2385 | $descr =~ s/\s*$//; |
2335 | - $descr =~ s/\s+/ /; | |
2386 | + $descr =~ s/\s+/ /g; | |
2336 | 2387 | $declaration_purpose = xml_escape($descr); |
2337 | 2388 | $in_purpose = 1; |
2338 | 2389 | } else { |
... | ... | @@ -2424,9 +2475,7 @@ |
2424 | 2475 | # Continued declaration purpose |
2425 | 2476 | chomp($declaration_purpose); |
2426 | 2477 | $declaration_purpose .= " " . xml_escape($1); |
2427 | - } elsif ($section =~ m/^Example/) { | |
2428 | - $_ =~ s/^\s*\*//; | |
2429 | - $contents .= $_; | |
2478 | + $declaration_purpose =~ s/\s+/ /g; | |
2430 | 2479 | } else { |
2431 | 2480 | $contents .= $1 . "\n"; |
2432 | 2481 | } |
... | ... | @@ -2489,6 +2538,9 @@ |
2489 | 2538 | } |
2490 | 2539 | if ($initial_section_counter == $section_counter) { |
2491 | 2540 | print STDERR "Warning(${file}): no structured comments found\n"; |
2541 | + if (($function_only == 1) && ($show_not_found == 1)) { | |
2542 | + print STDERR " Was looking for '$_'.\n" for keys %function_table; | |
2543 | + } | |
2492 | 2544 | if ($output_mode eq "xml") { |
2493 | 2545 | # The template wants at least one RefEntry here; make one. |
2494 | 2546 | print "<refentry>\n"; |