Pull documentation updates from Jonathan Corbet: "There's been a fair amount going on in the docs tree this time around, including: - Support for reproducible document builds, from Ben Hutchings and company. - The ability to automatically generate cross-reference links within a single DocBook book and embedded descriptions for large structures. From Danilo Cesar Lemes de Paula. - A new document on how to add a system call from David Drysdale. - Chameleon bus documentation from Johannes Thumshirn. ...plus the usual collection of improvements, typo fixes, and more" * tag 'docs-for-linus' of git://git.lwn.net/linux-2.6: (39 commits) Documentation, add kernel-parameters.txt entry for dis_ucode_ldr Documentation/x86: Rename IRQSTACKSIZE to IRQ_STACK_SIZE Documentation/Intel-IOMMU.txt: Modify definition of DRHD docs: update HOWTO for 3.x -> 4.x versioning kernel-doc: ignore unneeded attribute information scripts/kernel-doc: Adding cross-reference links to html documentation. DocBook: Fix non-determinstic installation of duplicate man pages Documentation: minor typo fix in mailbox.txt Documentation: describe how to add a system call doc: Add more workqueue functions to the documentation ARM: keystone: add documentation for SoCs and EVMs scripts/kernel-doc Allow struct arguments documentation in struct body SubmittingPatches: remove stray quote character Revert "DocBook: Avoid building man pages repeatedly and inconsistently" Documentation: Minor changes to men-chameleon-bus.txt Doc: fix trivial typo in SubmittingPatches MAINTAINERS: Direct Documentation/DocBook/media properly Documentation: installed man pages don't need to be executable fix Evolution submenu name in email-clients.txt Documentation: Add MCB documentation ...
Showing the changes to scripts (2 of 28 files). Show all
Unified · Split
| @@ -133,6 +133,30 @@ use strict; · 132 unmodified lines | |||
| 133 | # | 133 | # |
| 134 | # All descriptions can be multiline, except the short function description. | 134 | # All descriptions can be multiline, except the short function description. |
| 135 | # | 135 | # |
| 136 | # For really longs structs, you can also describe arguments inside the | ||
| 137 | # body of the struct. | ||
| 138 | # eg. | ||
| 139 | # /** | ||
| 140 | # * struct my_struct - short description | ||
| 141 | # * @a: first member | ||
| 142 | # * @b: second member | ||
| 143 | # * | ||
| 144 | # * Longer description | ||
| 145 | # */ | ||
| 146 | # struct my_struct { | ||
| 147 | # int a; | ||
| 148 | # int b; | ||
| 149 | # /** | ||
| 150 | # * @c: This is longer description of C | ||
| 151 | # * | ||
| 152 | # * You can use paragraphs to describe arguments | ||
| 153 | # * using this method. | ||
| 154 | # */ | ||
| 155 | # int c; | ||
| 156 | # }; | ||
| 157 | # | ||
| 158 | # This should be use only for struct/enum members. | ||
| 159 | # | ||
| 136 | # You can also add additional sections. When documenting kernel functions you | 160 | # You can also add additional sections. When documenting kernel functions you |
| 137 | # should document the "Context:" of the function, e.g. whether the functions | 161 | # should document the "Context:" of the function, e.g. whether the functions |
| 138 | # can be called form interrupts. Unlike other sections you can end it with an | 162 | # can be called form interrupts. Unlike other sections you can end it with an |
| @@ -253,11 +277,20 @@ my %highlights = %highlights_man; · 114 unmodified lines | |||
| 253 | my $blankline = $blankline_man; | 277 | my $blankline = $blankline_man; |
| 254 | my $modulename = "Kernel API"; | 278 | my $modulename = "Kernel API"; |
| 255 | my $function_only = 0; | 279 | my $function_only = 0; |
| 280 | my $show_not_found = 0; | ||
| 281 | |||
| 282 | my @build_time; | ||
| 283 | if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) && | ||
| 284 | (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') { | ||
| 285 | @build_time = gmtime($seconds); | ||
| 286 | } else { | ||
| 287 | @build_time = localtime; | ||
| 288 | } | ||
| 289 | |||
| 256 | my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', | 290 | my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', |
| 257 | 'July', 'August', 'September', 'October', | 291 | 'July', 'August', 'September', 'October', |
| 258 | 'November', 'December')[(localtime)[4]] . | 292 | 'November', 'December')[$build_time[4]] . |
| 259 | " " . ((localtime)[5]+1900); | 293 | " " . ($build_time[5]+1900); |
| 260 | my $show_not_found = 0; | ||
| 261 | 294 | ||
| 262 | # Essentially these are globals. | 295 | # Essentially these are globals. |
| 263 | # They probably want to be tidied up, made more localised or something. | 296 | # They probably want to be tidied up, made more localised or something. |
| @@ -287,9 +320,19 @@ my $lineprefix=""; · 23 unmodified lines | |||
| 287 | # 2 - scanning field start. | 320 | # 2 - scanning field start. |
| 288 | # 3 - scanning prototype. | 321 | # 3 - scanning prototype. |
| 289 | # 4 - documentation block | 322 | # 4 - documentation block |
| 323 | # 5 - gathering documentation outside main block | ||
| 290 | my $state; | 324 | my $state; |
| 291 | my $in_doc_sect; | 325 | my $in_doc_sect; |
| 292 | 326 | ||
| 327 | # Split Doc State | ||
| 328 | # 0 - Invalid (Before start or after finish) | ||
| 329 | # 1 - Is started (the /** was found inside a struct) | ||
| 330 | # 2 - The @parameter header was found, start accepting multi paragraph text. | ||
| 331 | # 3 - Finished (the */ was found) | ||
| 332 | # 4 - Error - Comment without header was found. Spit a warning as it's not | ||
| 333 | # proper kernel-doc and ignore the rest. | ||
| 334 | my $split_doc_state; | ||
| 335 | |||
| 293 | #declaration types: can be | 336 | #declaration types: can be |
| 294 | # 'function', 'struct', 'union', 'enum', 'typedef' | 337 | # 'function', 'struct', 'union', 'enum', 'typedef' |
| 295 | my $decl_type; | 338 | my $decl_type; |
| @@ -304,6 +347,9 @@ my $doc_decl = $doc_com . '(\w+)'; · 8 unmodified lines | |||
| 304 | my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)'; | 347 | my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)'; |
| 305 | my $doc_content = $doc_com_body . '(.*)'; | 348 | my $doc_content = $doc_com_body . '(.*)'; |
| 306 | my $doc_block = $doc_com . 'DOC:\s*(.*)?'; | 349 | my $doc_block = $doc_com . 'DOC:\s*(.*)?'; |
| 350 | my $doc_split_start = '^\s*/\*\*\s*$'; | ||
| 351 | my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)'; | ||
| 352 | my $doc_split_end = '^\s*\*/\s*$'; | ||
| 307 | 353 | ||
| 308 | my %constants; | 354 | my %constants; |
| 309 | my %parameterdescs; | 355 | my %parameterdescs; |
| @@ -1753,7 +1799,9 @@ sub dump_struct($$) { · 1443 unmodified lines | |||
| 1753 | # strip kmemcheck_bitfield_{begin,end}.*; | 1799 | # strip kmemcheck_bitfield_{begin,end}.*; |
| 1754 | $members =~ s/kmemcheck_bitfield_.*?;//gos; | 1800 | $members =~ s/kmemcheck_bitfield_.*?;//gos; |
| 1755 | # strip attributes | 1801 | # strip attributes |
| 1802 | $members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i; | ||
| 1756 | $members =~ s/__aligned\s*\([^;]*\)//gos; | 1803 | $members =~ s/__aligned\s*\([^;]*\)//gos; |
| 1804 | $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos; | ||
| 1757 | 1805 | ||
| 1758 | create_parameterlist($members, ';', $file); | 1806 | create_parameterlist($members, ';', $file); |
| 1759 | check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested); | 1807 | check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested); |
| @@ -2181,6 +2229,7 @@ sub reset_state { · 421 unmodified lines | |||
| 2181 | $prototype = ""; | 2229 | $prototype = ""; |
| 2182 | 2230 | ||
| 2183 | $state = 0; | 2231 | $state = 0; |
| 2232 | $split_doc_state = 0; | ||
| 2184 | } | 2233 | } |
| 2185 | 2234 | ||
| 2186 | sub tracepoint_munge($) { | 2235 | sub tracepoint_munge($) { |
| @@ -2453,7 +2502,6 @@ sub process_file($) { · 266 unmodified lines | |||
| 2453 | } | 2502 | } |
| 2454 | $section = $newsection; | 2503 | $section = $newsection; |
| 2455 | } elsif (/$doc_end/) { | 2504 | } elsif (/$doc_end/) { |
| 2456 | |||
| 2457 | if (($contents ne "") && ($contents ne "\n")) { | 2505 | if (($contents ne "") && ($contents ne "\n")) { |
| 2458 | dump_section($file, $section, xml_escape($contents)); | 2506 | dump_section($file, $section, xml_escape($contents)); |
| 2459 | $section = $section_default; | 2507 | $section = $section_default; |
| @@ -2494,8 +2542,44 @@ sub process_file($) { · 34 unmodified lines | |||
| 2494 | print STDERR "Warning(${file}:$.): bad line: $_"; | 2542 | print STDERR "Warning(${file}:$.): bad line: $_"; |
| 2495 | ++$warnings; | 2543 | ++$warnings; |
| 2496 | } | 2544 | } |
| 2545 | } elsif ($state == 5) { # scanning for split parameters | ||
| 2546 | # First line (state 1) needs to be a @parameter | ||
| 2547 | if ($split_doc_state == 1 && /$doc_split_sect/o) { | ||
| 2548 | $section = $1; | ||
| 2549 | $contents = $2; | ||
| 2550 | if ($contents ne "") { | ||
| 2551 | while ((substr($contents, 0, 1) eq " ") || | ||
| 2552 | substr($contents, 0, 1) eq "\t") { | ||
| 2553 | $contents = substr($contents, 1); | ||
| 2554 | } | ||
| 2555 | $contents .= "\n"; | ||
| 2556 | } | ||
| 2557 | $split_doc_state = 2; | ||
| 2558 | # Documentation block end */ | ||
| 2559 | } elsif (/$doc_split_end/) { | ||
| 2560 | if (($contents ne "") && ($contents ne "\n")) { | ||
| 2561 | dump_section($file, $section, xml_escape($contents)); | ||
| 2562 | $section = $section_default; | ||
| 2563 | $contents = ""; | ||
| 2564 | } | ||
| 2565 | $state = 3; | ||
| 2566 | $split_doc_state = 0; | ||
| 2567 | # Regular text | ||
| 2568 | } elsif (/$doc_content/) { | ||
| 2569 | if ($split_doc_state == 2) { | ||
| 2570 | $contents .= $1 . "\n"; | ||
| 2571 | } elsif ($split_doc_state == 1) { | ||
| 2572 | $split_doc_state = 4; | ||
| 2573 | print STDERR "Warning(${file}:$.): "; | ||
| 2574 | print STDERR "Incorrect use of kernel-doc format: $_"; | ||
| 2575 | ++$warnings; | ||
| 2576 | } | ||
| 2577 | } | ||
| 2497 | } elsif ($state == 3) { # scanning for function '{' (end of prototype) | 2578 | } elsif ($state == 3) { # scanning for function '{' (end of prototype) |
| 2498 | if ($decl_type eq 'function') { | 2579 | if (/$doc_split_start/) { |
| 2580 | $state = 5; | ||
| 2581 | $split_doc_state = 1; | ||
| 2582 | } elsif ($decl_type eq 'function') { | ||
| 2499 | process_state3_function($_, $file); | 2583 | process_state3_function($_, $file); |
| 2500 | } else { | 2584 | } else { |
| 2501 | process_state3_type($_, $file); | 2585 | process_state3_type($_, $file); |
| @@ -2587,7 +2671,7 @@ $kernelversion = get_kernel_version(); · 85 unmodified lines | |||
| 2587 | 2671 | ||
| 2588 | # generate a sequence of code that will splice in highlighting information | 2672 | # generate a sequence of code that will splice in highlighting information |
| 2589 | # using the s// operator. | 2673 | # using the s// operator. |
| 2590 | foreach my $pattern (keys %highlights) { | 2674 | foreach my $pattern (sort keys %highlights) { |
| 2591 | # print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n"; | 2675 | # print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n"; |
| 2592 | $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n"; | 2676 | $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n"; |
| 2593 | } | 2677 | } |
| @@ -0,0 +1,198 @@ | |||
| 1 | #!/usr/bin/perl -w | ||
| 2 | |||
| 3 | use strict; | ||
| 4 | |||
| 5 | ## Copyright (C) 2015 Intel Corporation ## | ||
| 6 | # ## | ||
| 7 | ## This software falls under the GNU General Public License. ## | ||
| 8 | ## Please read the COPYING file for more information ## | ||
| 9 | # | ||
| 10 | # | ||
| 11 | # This software reads a XML file and a list of valid interal | ||
| 12 | # references to replace Docbook tags with links. | ||
| 13 | # | ||
| 14 | # The list of "valid internal references" must be one-per-line in the following format: | ||
| 15 | # API-struct-foo | ||
| 16 | # API-enum-bar | ||
| 17 | # API-my-function | ||
| 18 | # | ||
| 19 | # The software walks over the XML file looking for xml tags representing possible references | ||
| 20 | # to the Document. Each reference will be cross checked against the "Valid Internal Reference" list. If | ||
| 21 | # the referece is found it replaces its content by a <link> tag. | ||
| 22 | # | ||
| 23 | # usage: | ||
| 24 | # kernel-doc-xml-ref -db filename | ||
| 25 | # xml filename > outputfile | ||
| 26 | |||
| 27 | # read arguments | ||
| 28 | if ($#ARGV != 2) { | ||
| 29 | usage(); | ||
| 30 | } | ||
| 31 | |||
| 32 | #Holds the database filename | ||
| 33 | my $databasefile; | ||
| 34 | my @database; | ||
| 35 | |||
| 36 | #holds the inputfile | ||
| 37 | my $inputfile; | ||
| 38 | my $errors = 0; | ||
| 39 | |||
| 40 | my %highlights = ( | ||
| 41 | "<function>(.*?)</function>", | ||
| 42 | "\"<function>\" . convert_function(\$1, \$line) . \"</function>\"", | ||
| 43 | "<structname>(.*?)</structname>", | ||
| 44 | "\"<structname>\" . convert_struct(\$1) . \"</structname>\"", | ||
| 45 | "<funcdef>(.*?)<function>(.*?)</function></funcdef>", | ||
| 46 | "\"<funcdef>\" . convert_param(\$1) . \"<function>\$2</function></funcdef>\"", | ||
| 47 | "<paramdef>(.*?)<parameter>(.*?)</parameter></paramdef>", | ||
| 48 | "\"<paramdef>\" . convert_param(\$1) . \"<parameter>\$2</parameter></paramdef>\""); | ||
| 49 | |||
| 50 | while($ARGV[0] =~ m/^-(.*)/) { | ||
| 51 | my $cmd = shift @ARGV; | ||
| 52 | if ($cmd eq "-db") { | ||
| 53 | $databasefile = shift @ARGV | ||
| 54 | } else { | ||
| 55 | usage(); | ||
| 56 | } | ||
| 57 | } | ||
| 58 | $inputfile = shift @ARGV; | ||
| 59 | |||
| 60 | sub open_database { | ||
| 61 | open (my $handle, '<', $databasefile) or die "Cannot open $databasefile"; | ||
| 62 | chomp(my @lines = <$handle>); | ||
| 63 | close $handle; | ||
| 64 | |||
| 65 | @database = @lines; | ||
| 66 | } | ||
| 67 | |||
| 68 | sub process_file { | ||
| 69 | open_database(); | ||
| 70 | |||
| 71 | my $dohighlight; | ||
| 72 | foreach my $pattern (keys %highlights) { | ||
| 73 | $dohighlight .= "\$line =~ s:$pattern:$highlights{$pattern}:eg;\n"; | ||
| 74 | } | ||
| 75 | |||
| 76 | open(FILE, $inputfile) or die("Could not open $inputfile") or die ("Cannot open $inputfile"); | ||
| 77 | foreach my $line (<FILE>) { | ||
| 78 | eval $dohighlight; | ||
| 79 | print $line; | ||
| 80 | } | ||
| 81 | } | ||
| 82 | |||
| 83 | sub trim($_) | ||
| 84 | { | ||
| 85 | my $str = $_[0]; | ||
| 86 | $str =~ s/^\s+|\s+$//g; | ||
| 87 | return $str | ||
| 88 | } | ||
| 89 | |||
| 90 | sub has_key_defined($_) | ||
| 91 | { | ||
| 92 | if ( grep( /^$_[0]$/, @database)) { | ||
| 93 | return 1; | ||
| 94 | } | ||
| 95 | return 0; | ||
| 96 | } | ||
| 97 | |||
| 98 | # Gets a <function> content and add it a hyperlink if possible. | ||
| 99 | sub convert_function($_) | ||
| 100 | { | ||
| 101 | my $arg = $_[0]; | ||
| 102 | my $key = $_[0]; | ||
| 103 | |||
| 104 | my $line = $_[1]; | ||
| 105 | |||
| 106 | $key = trim($key); | ||
| 107 | |||
| 108 | $key =~ s/[^A-Za-z0-9]/-/g; | ||
| 109 | $key = "API-" . $key; | ||
| 110 | |||
| 111 | # We shouldn't add links to <funcdef> prototype | ||
| 112 | if (!has_key_defined($key) || $line =~ m/\s+<funcdef/i) { | ||
| 113 | return $arg; | ||
| 114 | } | ||
| 115 | |||
| 116 | my $head = $arg; | ||
| 117 | my $tail = ""; | ||
| 118 | if ($arg =~ /(.*?)( ?)$/) { | ||
| 119 | $head = $1; | ||
| 120 | $tail = $2; | ||
| 121 | } | ||
| 122 | return "<link linkend=\"$key\">$head</link>$tail"; | ||
| 123 | } | ||
| 124 | |||
| 125 | # Converting a struct text to link | ||
| 126 | sub convert_struct($_) | ||
| 127 | { | ||
| 128 | my $arg = $_[0]; | ||
| 129 | my $key = $_[0]; | ||
| 130 | $key =~ s/(struct )?(\w)/$2/g; | ||
| 131 | $key =~ s/[^A-Za-z0-9]/-/g; | ||
| 132 | $key = "API-struct-" . $key; | ||
| 133 | |||
| 134 | if (!has_key_defined($key)) { | ||
| 135 | return $arg; | ||
| 136 | } | ||
| 137 | |||
| 138 | my ($head, $tail) = split_pointer($arg); | ||
| 139 | return "<link linkend=\"$key\">$head</link>$tail"; | ||
| 140 | } | ||
| 141 | |||
| 142 | # Identify "object *" elements | ||
| 143 | sub split_pointer($_) | ||
| 144 | { | ||
| 145 | my $arg = $_[0]; | ||
| 146 | if ($arg =~ /(.*?)( ?\* ?)/) { | ||
| 147 | return ($1, $2); | ||
| 148 | } | ||
| 149 | return ($arg, ""); | ||
| 150 | } | ||
| 151 | |||
| 152 | sub convert_param($_) | ||
| 153 | { | ||
| 154 | my $type = $_[0]; | ||
| 155 | my $keyname = convert_key_name($type); | ||
| 156 | |||
| 157 | if (!has_key_defined($keyname)) { | ||
| 158 | return $type; | ||
| 159 | } | ||
| 160 | |||
| 161 | my ($head, $tail) = split_pointer($type); | ||
| 162 | return "<link linkend=\"$keyname\">$head</link>$tail"; | ||
| 163 | |||
| 164 | } | ||
| 165 | |||
| 166 | # DocBook links are in the API-<TYPE>-<STRUCT-NAME> format | ||
| 167 | # This method gets an element and returns a valid DocBook reference for it. | ||
| 168 | sub convert_key_name($_) | ||
| 169 | { | ||
| 170 | #Pattern $2 is optional and might be uninitialized | ||
| 171 | no warnings 'uninitialized'; | ||
| 172 | |||
| 173 | my $str = $_[0]; | ||
| 174 | $str =~ s/(const|static)? ?(struct)? ?([a-zA-Z0-9_]+) ?(\*|&)?/$2 $3/g ; | ||
| 175 | |||
| 176 | # trim | ||
| 177 | $str =~ s/^\s+|\s+$//g; | ||
| 178 | |||
| 179 | # spaces and _ to - | ||
| 180 | $str =~ s/[^A-Za-z0-9]/-/g; | ||
| 181 | |||
| 182 | return "API-" . $str; | ||
| 183 | } | ||
| 184 | |||
| 185 | sub usage { | ||
| 186 | print "Usage: $0 -db database filename\n"; | ||
| 187 | print " xml source file(s) > outputfile\n"; | ||
| 188 | exit 1; | ||
| 189 | } | ||
| 190 | |||
| 191 | # starting point | ||
| 192 | process_file(); | ||
| 193 | |||
| 194 | if ($errors) { | ||
| 195 | print STDERR "$errors errors\n"; | ||
| 196 | } | ||
| 197 | |||
| 198 | exit($errors); | ||