History

Merge tag 'docs-5.13' of git://git.lwn.net/linux

Pull documentation updates from Jonathan Corbet: "It's been a relatively busy cycle in docsland, though more than usually well contained to Documentation/ itself. Highlights include: - The Chinese translators have been busy and show no signs of stopping anytime soon. Italian has also caught up. - Aditya Srivastava has been working on improvements to the kernel-doc script. - Thorsten continues his work on reporting-issues.rst and related documentation around regression reporting. - Lots of documentation updates, typo fixes, etc. as usual" * tag 'docs-5.13' of git://git.lwn.net/linux: (139 commits) docs/zh_CN: add openrisc translation to zh_CN index docs/zh_CN: add openrisc index.rst translation docs/zh_CN: add openrisc todo.rst translation docs/zh_CN: add openrisc openrisc_port.rst translation docs/zh_CN: add core api translation to zh_CN index docs/zh_CN: add core-api index.rst translation docs/zh_CN: add core-api irq index.rst translation docs/zh_CN: add core-api irq irqflags-tracing.rst translation docs/zh_CN: add core-api irq irq-domain.rst translation docs/zh_CN: add core-api irq irq-affinity.rst translation docs/zh_CN: add core-api irq concepts.rst translation docs: sphinx-pre-install: don't barf on beta Sphinx releases scripts: kernel-doc: improve parsing for kernel-doc comments syntax docs/zh_CN: two minor fixes in zh_CN/doc-guide/ Documentation: dev-tools: Add Testing Overview docs/zh_CN: add translations in zh_CN/dev-tools/gcov docs: reporting-issues: make people CC the regressions list MAINTAINERS: add regressions mailing list doc:it_IT: align Italian documentation docs/zh_CN: sync reporting-issues.rst ...

Linus Torvalds committed 5 years ago

Commit 2f9ef052 parents 0c85556 441ca97133 files · +9868 −2059Browse files

Showing the changes to scripts (4 of 133 files). Show all

Unified · Split

4 files
  1. scripts/checkpatch.pl +113 −20
  2. scripts/get_abi.pl +53 −21
  3. scripts/kernel-doc +52 −8
  4. scripts/sphinx-pre-install +1 −1
scripts/checkpatch.pl+113−20
@@ -23,6 +23,9 @@ my $V = '0.32'; · 22 unmodified lines
2323 use Getopt::Long qw(:config no_auto_abbrev);
2424
2525 my $quiet = 0;
26+my $verbose = 0;
27+my %verbose_messages = ();
28+my %verbose_emitted = ();
2629 my $tree = 1;
2730 my $chk_signoff = 1;
2831 my $chk_patch = 1;
@@ -61,6 +64,7 @@ my $spelling_file = "$D/spelling.txt"; · 32 unmodified lines
6164 my $codespell = 0;
6265 my $codespellfile = "/usr/share/codespell/dictionary.txt";
6366 my $conststructsfile = "$D/const_structs.checkpatch";
67+my $docsfile = "$D/../Documentation/dev-tools/checkpatch.rst";
6468 my $typedefsfile;
6569 my $color = "auto";
6670 my $allow_c99_comments = 1; # Can be overridden by --ignore C99_COMMENT_TOLERANCE
@@ -78,6 +82,7 @@ Version: $V · 11 unmodified lines
7882
7983 Options:
8084 -q, --quiet quiet
85+ -v, --verbose verbose mode
8186 --no-tree run without a kernel tree
8287 --no-signoff do not check for 'Signed-off-by' line
8388 --patch treat FILE as patchfile (default)
@@ -158,15 +163,51 @@ sub list_types { · 74 unmodified lines
158163 my $text = <$script>;
159164 close($script);
160165
161− my @types = ();
166+ my %types = ();
162167 # Also catch when type or level is passed through a variable
163− for ($text =~ /(?:(?:\bCHK|\bWARN|\bERROR|&\{\$msg_level})\s*\(|\$msg_type\s*=)\s*"([^"]+)"/g) {
164− push (@types, $_);
168+ while ($text =~ /(?:(\bCHK|\bWARN|\bERROR|&\{\$msg_level})\s*\(|\$msg_type\s*=)\s*"([^"]+)"/g) {
169+ if (defined($1)) {
170+ if (exists($types{$2})) {
171+ $types{$2} .= ",$1" if ($types{$2} ne $1);
172+ } else {
173+ $types{$2} = $1;
174+ }
175+ } else {
176+ $types{$2} = "UNDETERMINED";
177+ }
165178 }
166− @types = sort(uniq(@types));
179+
167180 print("#\tMessage type\n\n");
168− foreach my $type (@types) {
181+ if ($color) {
182+ print(" ( Color coding: ");
183+ print(RED . "ERROR" . RESET);
184+ print(" | ");
185+ print(YELLOW . "WARNING" . RESET);
186+ print(" | ");
187+ print(GREEN . "CHECK" . RESET);
188+ print(" | ");
189+ print("Multiple levels / Undetermined");
190+ print(" )\n\n");
191+ }
192+
193+ foreach my $type (sort keys %types) {
194+ my $orig_type = $type;
195+ if ($color) {
196+ my $level = $types{$type};
197+ if ($level eq "ERROR") {
198+ $type = RED . $type . RESET;
199+ } elsif ($level eq "WARN") {
200+ $type = YELLOW . $type . RESET;
201+ } elsif ($level eq "CHK") {
202+ $type = GREEN . $type . RESET;
203+ }
204+ }
169205 print(++$count . "\t" . $type . "\n");
206+ if ($verbose && exists($verbose_messages{$orig_type})) {
207+ my $message = $verbose_messages{$orig_type};
208+ $message =~ s/\n/\n\t/g;
209+ print("\t" . $message . "\n\n");
210+ }
170211 }
171212
172213 exit($exitcode);
@@ -198,6 +239,46 @@ if (-f $conf) { · 25 unmodified lines
198239 unshift(@ARGV, @conf_args) if @conf_args;
199240 }
200241
242+sub load_docs {
243+ open(my $docs, '<', "$docsfile")
244+ or warn "$P: Can't read the documentation file $docsfile $!\n";
245+
246+ my $type = '';
247+ my $desc = '';
248+ my $in_desc = 0;
249+
250+ while (<$docs>) {
251+ chomp;
252+ my $line = $_;
253+ $line =~ s/\s+$//;
254+
255+ if ($line =~ /^\s*\*\*(.+)\*\*$/) {
256+ if ($desc ne '') {
257+ $verbose_messages{$type} = trim($desc);
258+ }
259+ $type = $1;
260+ $desc = '';
261+ $in_desc = 1;
262+ } elsif ($in_desc) {
263+ if ($line =~ /^(?:\s{4,}|$)/) {
264+ $line =~ s/^\s{4}//;
265+ $desc .= $line;
266+ $desc .= "\n";
267+ } else {
268+ $verbose_messages{$type} = trim($desc);
269+ $type = '';
270+ $desc = '';
271+ $in_desc = 0;
272+ }
273+ }
274+ }
275+
276+ if ($desc ne '') {
277+ $verbose_messages{$type} = trim($desc);
278+ }
279+ close($docs);
280+}
281+
201282 # Perl's Getopt::Long allows options to take optional arguments after a space.
202283 # Prevent --color by itself from consuming other arguments
203284 foreach (@ARGV) {
@@ -208,6 +289,7 @@ foreach (@ARGV) { · 4 unmodified lines
208289
209290 GetOptions(
210291 'q|quiet+' => \$quiet,
292+ 'v|verbose!' => \$verbose,
211293 'tree!' => \$tree,
212294 'signoff!' => \$chk_signoff,
213295 'patch!' => \$chk_patch,
@@ -247,13 +329,27 @@ GetOptions( · 33 unmodified lines
247329
248330 help(0) if ($help);
249331
332+die "$P: --git cannot be used with --file or --fix\n" if ($git && ($file || $fix));
333+die "$P: --verbose cannot be used with --terse\n" if ($verbose && $terse);
334+
335+if ($color =~ /^[01]$/) {
336+ $color = !$color;
337+} elsif ($color =~ /^always$/i) {
338+ $color = 1;
339+} elsif ($color =~ /^never$/i) {
340+ $color = 0;
341+} elsif ($color =~ /^auto$/i) {
342+ $color = (-t STDOUT);
343+} else {
344+ die "$P: Invalid color mode: $color\n";
345+}
346+
347+load_docs() if ($verbose);
250348 list_types(0) if ($list_types);
251349
252350 $fix = 1 if ($fix_inplace);
253351 $check_orig = $check;
254352
255−die "$P: --git cannot be used with --file or --fix\n" if ($git && ($file || $fix));
256−
257353 my $exit = 0;
258354
259355 my $perl_version_ok = 1;
@@ -268,18 +364,6 @@ if ($#ARGV < 0) { · 8 unmodified lines
268364 push(@ARGV, '-');
269365 }
270366
271−if ($color =~ /^[01]$/) {
272− $color = !$color;
273−} elsif ($color =~ /^always$/i) {
274− $color = 1;
275−} elsif ($color =~ /^never$/i) {
276− $color = 0;
277−} elsif ($color =~ /^auto$/i) {
278− $color = (-t STDOUT);
279−} else {
280− die "$P: Invalid color mode: $color\n";
281−}
282−
283367 # skip TAB size 1 to avoid additional checks on $tabsize - 1
284368 die "$P: Invalid TAB size: $tabsize\n" if ($tabsize < 2);
285369
@@ -2209,7 +2293,16 @@ sub report { · 1923 unmodified lines
22092293 splice(@lines, 1, 1);
22102294 $output = join("\n", @lines);
22112295 }
2212− $output = (split('\n', $output))[0] . "\n" if ($terse);
2296+
2297+ if ($terse) {
2298+ $output = (split('\n', $output))[0] . "\n";
2299+ }
2300+
2301+ if ($verbose && exists($verbose_messages{$type}) &&
2302+ !exists($verbose_emitted{$type})) {
2303+ $output .= $verbose_messages{$type} . "\n\n";
2304+ $verbose_emitted{$type} = 1;
2305+ }
22132306
22142307 push(our @report, $output);
22152308
scripts/get_abi.pl+53−21
@@ -281,8 +281,12 @@ sub create_labels { · 280 unmodified lines
281281 # Outputs the book on ReST format
282282 #
283283
284−# \b doesn't work well with paths. So, we need to define something else
285−my $bondary = qr { (?<![\w\/\`\{])(?=[\w\/\`\{])|(?<=[\w\/\`\{])(?![\w\/\`\{]) }x;
284+# \b doesn't work well with paths. So, we need to define something else:
285+# Boundaries are punct characters, spaces and end-of-line
286+my $start = qr {(^|\s|\() }x;
287+my $bondary = qr { ([,.:;\)\s]|\z) }x;
288+my $xref_match = qr { $start(\/(sys|config|proc|dev|kvd)\/[^,.:;\)\s]+)$bondary }x;
289+my $symbols = qr { ([\x01-\x08\x0e-\x1f\x21-\x2f\x3a-\x40\x7b-\xff]) }x;
286290
287291 sub output_rest {
288292 create_labels();
@@ -305,7 +309,6 @@ sub output_rest { · 16 unmodified lines
305309 }
306310
307311 my $w = $what;
308− $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
309312
310313 if ($type ne "File") {
311314 my $cur_part = $what;
@@ -329,6 +332,7 @@ sub output_rest { · 17 unmodified lines
329332 my $len = 0;
330333
331334 foreach my $name (@names) {
335+ $name =~ s/$symbols/\\$1/g;
332336 $name = "**$name**";
333337 $len = length($name) if (length($name) > $len);
334338 }
@@ -377,32 +381,60 @@ sub output_rest { · 42 unmodified lines
377381
378382 # Enrich text by creating cross-references
379383
380− $desc =~ s,Documentation/(?!devicetree)(\S+)\.rst,:doc:`/$1`,g;
384+ my $new_desc = "";
385+ my $init_indent = -1;
386+ my $literal_indent = -1;
387+
388+ open(my $fh, "+<", \$desc);
389+ while (my $d = <$fh>) {
390+ my $indent = $d =~ m/^(\s+)/;
391+ my $spaces = length($indent);
392+ $init_indent = $indent if ($init_indent < 0);
393+ if ($literal_indent >= 0) {
394+ if ($spaces > $literal_indent) {
395+ $new_desc .= $d;
396+ next;
397+ } else {
398+ $literal_indent = -1;
399+ }
400+ } else {
401+ if ($d =~ /()::$/ && !($d =~ /^\s*\.\./)) {
402+ $literal_indent = $spaces;
403+ }
404+ }
381405
382− my @matches = $desc =~ m,Documentation/ABI/([\w\/\-]+),;
383− foreach my $f (@matches) {
384− my $xref = $f;
385− my $path = $f;
386− $path =~ s,.*/(.*/.*),$1,;;
387− $path =~ s,[/\-],_,g;;
388− $xref .= " <abi_file_" . $path . ">";
389− $desc =~ s,\bDocumentation/ABI/$f\b,:ref:`$xref`,g;
390− }
406+ $d =~ s,Documentation/(?!devicetree)(\S+)\.rst,:doc:`/$1`,g;
391407
392− @matches = $desc =~ m,$bondary(/sys/[^\s\.\,\;\:\*\s\`\'\(\)]+)$bondary,;
408+ my @matches = $d =~ m,Documentation/ABI/([\w\/\-]+),g;
409+ foreach my $f (@matches) {
410+ my $xref = $f;
411+ my $path = $f;
412+ $path =~ s,.*/(.*/.*),$1,;;
413+ $path =~ s,[/\-],_,g;;
414+ $xref .= " <abi_file_" . $path . ">";
415+ $d =~ s,\bDocumentation/ABI/$f\b,:ref:`$xref`,g;
416+ }
417+
418+ # Seek for cross reference symbols like /sys/...
419+ @matches = $d =~ m/$xref_match/g;
393420
394− foreach my $s (@matches) {
395− if (defined($data{$s}) && defined($data{$s}->{label})) {
396− my $xref = $s;
421+ foreach my $s (@matches) {
422+ next if (!($s =~ m,/,));
423+ if (defined($data{$s}) && defined($data{$s}->{label})) {
424+ my $xref = $s;
397425
398− $xref =~ s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g;
399− $xref = ":ref:`$xref <" . $data{$s}->{label} . ">`";
426+ $xref =~ s/$symbols/\\$1/g;
427+ $xref = ":ref:`$xref <" . $data{$s}->{label} . ">`";
400428
401− $desc =~ s,$bondary$s$bondary,$xref,g;
429+ $d =~ s,$start$s$bondary,$1$xref$2,g;
430+ }
402431 }
432+ $new_desc .= $d;
403433 }
434+ close $fh;
435+
404436
405− print "$desc\n\n";
437+ print "$new_desc\n\n";
406438 } else {
407439 $desc =~ s/^\s+//;
408440
scripts/kernel-doc+52−8
@@ -391,8 +391,14 @@ my $doc_com = '\s*\*\s*'; · 390 unmodified lines
391391 my $doc_com_body = '\s*\* ?';
392392 my $doc_decl = $doc_com . '(\w+)';
393393 # @params and a strictly limited set of supported section names
394+# Specifically:
395+# Match @word:
396+# @...:
397+# @{section-name}:
398+# while trying to not match literal block starts like "example::"
399+#
394400 my $doc_sect = $doc_com .
395− '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
401+ '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:].*)?$';
396402 my $doc_content = $doc_com_body . '(.*)';
397403 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
398404 my $doc_inline_start = '^\s*/\*\*\s*$';
@@ -1201,12 +1207,23 @@ sub dump_union($$) { · 802 unmodified lines
12011207 sub dump_struct($$) {
12021208 my $x = shift;
12031209 my $file = shift;
1210+ my $decl_type;
1211+ my $members;
1212+ my $type = qr{struct|union};
1213+ # For capturing struct/union definition body, i.e. "{members*}qualifiers*"
1214+ my $definition_body = qr{\{(.*)\}(?:\s*(?:__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*};
12041215
1205− if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) {
1206− my $decl_type = $1;
1216+ if ($x =~ /($type)\s+(\w+)\s*$definition_body/) {
1217+ $decl_type = $1;
12071218 $declaration_name = $2;
1208− my $members = $3;
1219+ $members = $3;
1220+ } elsif ($x =~ /typedef\s+($type)\s*$definition_body\s*(\w+)\s*;/) {
1221+ $decl_type = $1;
1222+ $declaration_name = $3;
1223+ $members = $2;
1224+ }
12091225
1226+ if ($members) {
12101227 if ($identifier ne $declaration_name) {
12111228 print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n";
12121229 return;
@@ -1401,9 +1418,14 @@ sub dump_enum($$) { · 188 unmodified lines
14011418
14021419 if ($members) {
14031420 if ($identifier ne $declaration_name) {
1404− print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n";
1421+ if ($identifier eq "") {
1422+ print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
1423+ } else {
1424+ print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n";
1425+ }
14051426 return;
14061427 }
1428+ $declaration_name = "(anonymous)" if ($declaration_name eq "");
14071429
14081430 my %_members;
14091431
@@ -1755,12 +1777,14 @@ sub dump_function($$) { · 345 unmodified lines
17551777 $prototype =~ s/^noinline +//;
17561778 $prototype =~ s/__init +//;
17571779 $prototype =~ s/__init_or_module +//;
1780+ $prototype =~ s/__flatten +//;
17581781 $prototype =~ s/__meminit +//;
17591782 $prototype =~ s/__must_check +//;
17601783 $prototype =~ s/__weak +//;
17611784 $prototype =~ s/__sched +//;
17621785 $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//;
17631786 my $define = $prototype =~ s/^#\s*define\s+//; #ak added
1787+ $prototype =~ s/__attribute_const__ +//;
17641788 $prototype =~ s/__attribute__\s*\(\(
17651789 (?:
17661790 [\w\s]++ # attribute name
@@ -2085,15 +2109,28 @@ sub process_name($$) { · 318 unmodified lines
20852109 }
20862110 } elsif (/$doc_decl/o) {
20872111 $identifier = $1;
2088− if (/\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) {
2112+ my $is_kernel_comment = 0;
2113+ my $decl_start = qr{\s*\*};
2114+ # test for pointer declaration type, foo * bar() - desc
2115+ my $fn_type = qr{\w+\s*\*\s*};
2116+ my $parenthesis = qr{\(\w*\)};
2117+ my $decl_end = qr{[-:].*};
2118+ if (/^$decl_start\s*([\w\s]+?)$parenthesis?\s*$decl_end?$/) {
20892119 $identifier = $1;
20902120 }
20912121 if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) {
20922122 $decl_type = $1;
20932123 $identifier = $2;
2094− } else {
2124+ $is_kernel_comment = 1;
2125+ }
2126+ # Look for foo() or static void foo() - description; or misspelt
2127+ # identifier
2128+ elsif (/^$decl_start\s*$fn_type?(\w+)\s*$parenthesis?\s*$decl_end?$/ ||
2129+ /^$decl_start\s*$fn_type?(\w+.*)$parenthesis?\s*$decl_end$/) {
2130+ $identifier = $1;
20952131 $decl_type = 'function';
20962132 $identifier =~ s/^define\s+//;
2133+ $is_kernel_comment = 1;
20972134 }
20982135 $identifier =~ s/\s+$//;
20992136
@@ -2115,13 +2152,20 @@ sub process_name($$) { · 15 unmodified lines
21152152 $declaration_purpose = "";
21162153 }
21172154
2155+ if (!$is_kernel_comment) {
2156+ print STDERR "${file}:$.: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n";
2157+ print STDERR $_;
2158+ ++$warnings;
2159+ $state = STATE_NORMAL;
2160+ }
2161+
21182162 if (($declaration_purpose eq "") && $verbose) {
21192163 print STDERR "${file}:$.: warning: missing initial short description on line:\n";
21202164 print STDERR $_;
21212165 ++$warnings;
21222166 }
21232167
2124− if ($identifier eq "") {
2168+ if ($identifier eq "" && $decl_type ne "enum") {
21252169 print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
21262170 print STDERR $_;
21272171 ++$warnings;
scripts/sphinx-pre-install+1−1
@@ -259,7 +259,7 @@ sub get_sphinx_version($) · 258 unmodified lines
259259
260260 open IN, "$cmd --version 2>&1 |";
261261 while (<IN>) {
262− if (m/^\s*sphinx-build\s+([\d\.]+)(\+\/[\da-f]+)?$/) {
262+ if (m/^\s*sphinx-build\s+([\d\.]+)((\+\/[\da-f]+)|(b\d+))?$/) {
263263 $ver=$1;
264264 last;
265265 }