kernel-doc (03ab8e6297acd1bc0eedaa050e2a1635c576fd11) kernel-doc (df4bf98ec2d199ae32f215d083774ebb6424bf1f)
1#!/usr/bin/env perl
2# SPDX-License-Identifier: GPL-2.0
3
4use warnings;
5use strict;
6
7## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
8## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##

--- 413 unchanged lines hidden (view full) ---

422
423#
424sub print_lineno {
425 my $lineno = shift;
426 if ($enable_lineno && defined($lineno)) {
427 print ".. LINENO " . $lineno . "\n";
428 }
429}
1#!/usr/bin/env perl
2# SPDX-License-Identifier: GPL-2.0
3
4use warnings;
5use strict;
6
7## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
8## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##

--- 413 unchanged lines hidden (view full) ---

422
423#
424sub print_lineno {
425 my $lineno = shift;
426 if ($enable_lineno && defined($lineno)) {
427 print ".. LINENO " . $lineno . "\n";
428 }
429}
430
431sub emit_warning {
432 my $location = shift;
433 my $msg = shift;
434 print STDERR "$location: warning: $msg";
435 ++$warnings;
436}
430##
431# dumps section contents to arrays/hashes intended for that purpose.
432#
433sub dump_section {
434 my $file = shift;
435 my $name = shift;
436 my $contents = join "\n", @_;
437

--- 8 unchanged lines hidden (view full) ---

446 $parameterdescs{$name} = $contents;
447 $sectcheck = $sectcheck . $name . " ";
448 $parameterdesc_start_lines{$name} = $new_start_line;
449 $new_start_line = 0;
450 } else {
451 if (defined($sections{$name}) && ($sections{$name} ne "")) {
452 # Only warn on user specified duplicate section names.
453 if ($name ne $section_default) {
437##
438# dumps section contents to arrays/hashes intended for that purpose.
439#
440sub dump_section {
441 my $file = shift;
442 my $name = shift;
443 my $contents = join "\n", @_;
444

--- 8 unchanged lines hidden (view full) ---

453 $parameterdescs{$name} = $contents;
454 $sectcheck = $sectcheck . $name . " ";
455 $parameterdesc_start_lines{$name} = $new_start_line;
456 $new_start_line = 0;
457 } else {
458 if (defined($sections{$name}) && ($sections{$name} ne "")) {
459 # Only warn on user specified duplicate section names.
460 if ($name ne $section_default) {
454 print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
455 ++$warnings;
461 emit_warning("${file}:$.", "duplicate section name '$name'\n");
456 }
457 $sections{$name} .= $contents;
458 } else {
459 $sections{$name} = $contents;
460 push @sectionlist, $name;
461 $section_start_lines{$name} = $new_start_line;
462 $new_start_line = 0;
463 }

--- 625 unchanged lines hidden (view full) ---

1089 } elsif ($x =~ /typedef\s+($type)\s*$definition_body\s*(\w+)\s*;/) {
1090 $decl_type = $1;
1091 $declaration_name = $3;
1092 $members = $2;
1093 }
1094
1095 if ($members) {
1096 if ($identifier ne $declaration_name) {
462 }
463 $sections{$name} .= $contents;
464 } else {
465 $sections{$name} = $contents;
466 push @sectionlist, $name;
467 $section_start_lines{$name} = $new_start_line;
468 $new_start_line = 0;
469 }

--- 625 unchanged lines hidden (view full) ---

1095 } elsif ($x =~ /typedef\s+($type)\s*$definition_body\s*(\w+)\s*;/) {
1096 $decl_type = $1;
1097 $declaration_name = $3;
1098 $members = $2;
1099 }
1100
1101 if ($members) {
1102 if ($identifier ne $declaration_name) {
1097 print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n";
1103 emit_warning("${file}:$.", "expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n");
1098 return;
1099 }
1100
1101 # ignore members marked private:
1102 $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
1103 $members =~ s/\/\*\s*private:.*//gosi;
1104 # strip comments:
1105 $members =~ s/\/\*.*?\*\///gos;

--- 187 unchanged lines hidden (view full) ---

1293 } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
1294 $declaration_name = $1;
1295 $members = $2;
1296 }
1297
1298 if ($members) {
1299 if ($identifier ne $declaration_name) {
1300 if ($identifier eq "") {
1104 return;
1105 }
1106
1107 # ignore members marked private:
1108 $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
1109 $members =~ s/\/\*\s*private:.*//gosi;
1110 # strip comments:
1111 $members =~ s/\/\*.*?\*\///gos;

--- 187 unchanged lines hidden (view full) ---

1299 } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
1300 $declaration_name = $1;
1301 $members = $2;
1302 }
1303
1304 if ($members) {
1305 if ($identifier ne $declaration_name) {
1306 if ($identifier eq "") {
1301 print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
1307 emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n");
1302 } else {
1308 } else {
1303 print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n";
1309 emit_warning("${file}:$.", "expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n");
1304 }
1305 return;
1306 }
1307 $declaration_name = "(anonymous)" if ($declaration_name eq "");
1308
1309 my %_members;
1310
1311 $members =~ s/\s+$//;
1312
1313 foreach my $arg (split ',', $members) {
1314 $arg =~ s/^\s*(\w+).*/$1/;
1315 push @parameterlist, $arg;
1316 if (!$parameterdescs{$arg}) {
1317 $parameterdescs{$arg} = $undescribed;
1318 if (show_warnings("enum", $declaration_name)) {
1310 }
1311 return;
1312 }
1313 $declaration_name = "(anonymous)" if ($declaration_name eq "");
1314
1315 my %_members;
1316
1317 $members =~ s/\s+$//;
1318
1319 foreach my $arg (split ',', $members) {
1320 $arg =~ s/^\s*(\w+).*/$1/;
1321 push @parameterlist, $arg;
1322 if (!$parameterdescs{$arg}) {
1323 $parameterdescs{$arg} = $undescribed;
1324 if (show_warnings("enum", $declaration_name)) {
1319 print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum '$declaration_name'\n";
1325 emit_warning("${file}:$.", "Enum value '$arg' not described in enum '$declaration_name'\n");
1320 }
1321 }
1322 $_members{$arg} = 1;
1323 }
1324
1325 while (my ($k, $v) = each %parameterdescs) {
1326 if (!exists($_members{$k})) {
1327 if (show_warnings("enum", $declaration_name)) {
1326 }
1327 }
1328 $_members{$arg} = 1;
1329 }
1330
1331 while (my ($k, $v) = each %parameterdescs) {
1332 if (!exists($_members{$k})) {
1333 if (show_warnings("enum", $declaration_name)) {
1328 print STDERR "${file}:$.: warning: Excess enum value '$k' description in '$declaration_name'\n";
1334 emit_warning("${file}:$.", "Excess enum value '$k' description in '$declaration_name'\n");
1329 }
1330 }
1331 }
1332
1333 output_declaration($declaration_name,
1334 'enum',
1335 {'enum' => $declaration_name,
1336 'module' => $modulename,

--- 25 unchanged lines hidden (view full) ---

1362 # Parse function typedef prototypes
1363 if ($x =~ $typedef1 || $x =~ $typedef2) {
1364 $return_type = $1;
1365 $declaration_name = $2;
1366 my $args = $3;
1367 $return_type =~ s/^\s+//;
1368
1369 if ($identifier ne $declaration_name) {
1335 }
1336 }
1337 }
1338
1339 output_declaration($declaration_name,
1340 'enum',
1341 {'enum' => $declaration_name,
1342 'module' => $modulename,

--- 25 unchanged lines hidden (view full) ---

1368 # Parse function typedef prototypes
1369 if ($x =~ $typedef1 || $x =~ $typedef2) {
1370 $return_type = $1;
1371 $declaration_name = $2;
1372 my $args = $3;
1373 $return_type =~ s/^\s+//;
1374
1375 if ($identifier ne $declaration_name) {
1370 print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
1376 emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n");
1371 return;
1372 }
1373
1374 create_parameterlist($args, ',', $file, $declaration_name);
1375
1376 output_declaration($declaration_name,
1377 'function',
1378 {'function' => $declaration_name,

--- 14 unchanged lines hidden (view full) ---

1393 $x =~ s/\(*.\)\s*;$/;/;
1394 $x =~ s/\[*.\]\s*;$/;/;
1395 }
1396
1397 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1398 $declaration_name = $1;
1399
1400 if ($identifier ne $declaration_name) {
1377 return;
1378 }
1379
1380 create_parameterlist($args, ',', $file, $declaration_name);
1381
1382 output_declaration($declaration_name,
1383 'function',
1384 {'function' => $declaration_name,

--- 14 unchanged lines hidden (view full) ---

1399 $x =~ s/\(*.\)\s*;$/;/;
1400 $x =~ s/\[*.\]\s*;$/;/;
1401 }
1402
1403 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1404 $declaration_name = $1;
1405
1406 if ($identifier ne $declaration_name) {
1401 print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
1407 emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n");
1402 return;
1403 }
1404
1405 output_declaration($declaration_name,
1406 'typedef',
1407 {'typedef' => $declaration_name,
1408 'module' => $modulename,
1409 'sectionlist' => \@sectionlist,

--- 139 unchanged lines hidden (view full) ---

1549 # warn if parameter has no description
1550 # (but ignore ones starting with # as these are not parameters
1551 # but inline preprocessor statements);
1552 # Note: It will also ignore void params and unnamed structs/unions
1553 if (!defined $parameterdescs{$param} && $param !~ /^#/) {
1554 $parameterdescs{$param} = $undescribed;
1555
1556 if (show_warnings($type, $declaration_name) && $param !~ /\./) {
1408 return;
1409 }
1410
1411 output_declaration($declaration_name,
1412 'typedef',
1413 {'typedef' => $declaration_name,
1414 'module' => $modulename,
1415 'sectionlist' => \@sectionlist,

--- 139 unchanged lines hidden (view full) ---

1555 # warn if parameter has no description
1556 # (but ignore ones starting with # as these are not parameters
1557 # but inline preprocessor statements);
1558 # Note: It will also ignore void params and unnamed structs/unions
1559 if (!defined $parameterdescs{$param} && $param !~ /^#/) {
1560 $parameterdescs{$param} = $undescribed;
1561
1562 if (show_warnings($type, $declaration_name) && $param !~ /\./) {
1557 print STDERR
1558 "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
1559 ++$warnings;
1563 emit_warning("${file}:$.", "Function parameter or member '$param' not described in '$declaration_name'\n");
1560 }
1561 }
1562
1563 # strip spaces from $param so that it is one continuous string
1564 # on @parameterlist;
1565 # this fixes a problem where check_sections() cannot find
1566 # a parameter like "addr[6 + 2]" because it actually appears
1567 # as "addr[6", "+", "2]" on the parameter list;

--- 31 unchanged lines hidden (view full) ---

1599 ##$prm_clean =~ s/^\**//;
1600 if ($prm_clean eq $sects[$sx]) {
1601 $err = 0;
1602 last;
1603 }
1604 }
1605 if ($err) {
1606 if ($decl_type eq "function") {
1564 }
1565 }
1566
1567 # strip spaces from $param so that it is one continuous string
1568 # on @parameterlist;
1569 # this fixes a problem where check_sections() cannot find
1570 # a parameter like "addr[6 + 2]" because it actually appears
1571 # as "addr[6", "+", "2]" on the parameter list;

--- 31 unchanged lines hidden (view full) ---

1603 ##$prm_clean =~ s/^\**//;
1604 if ($prm_clean eq $sects[$sx]) {
1605 $err = 0;
1606 last;
1607 }
1608 }
1609 if ($err) {
1610 if ($decl_type eq "function") {
1607 print STDERR "${file}:$.: warning: " .
1611 emit_warning("${file}:$.",
1608 "Excess function parameter " .
1609 "'$sects[$sx]' " .
1612 "Excess function parameter " .
1613 "'$sects[$sx]' " .
1610 "description in '$decl_name'\n";
1611 ++$warnings;
1614 "description in '$decl_name'\n");
1612 }
1613 }
1614 }
1615}
1616
1617##
1618# Checks the section describing the return value of a function.
1619sub check_return_section {

--- 4 unchanged lines hidden (view full) ---

1624 # Ignore an empty return type (It's a macro)
1625 # Ignore functions with a "void" return type. (But don't ignore "void *")
1626 if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
1627 return;
1628 }
1629
1630 if (!defined($sections{$section_return}) ||
1631 $sections{$section_return} eq "") {
1615 }
1616 }
1617 }
1618}
1619
1620##
1621# Checks the section describing the return value of a function.
1622sub check_return_section {

--- 4 unchanged lines hidden (view full) ---

1627 # Ignore an empty return type (It's a macro)
1628 # Ignore functions with a "void" return type. (But don't ignore "void *")
1629 if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
1630 return;
1631 }
1632
1633 if (!defined($sections{$section_return}) ||
1634 $sections{$section_return} eq "") {
1632 print STDERR "${file}:$.: warning: " .
1635 emit_warning("${file}:$.",
1633 "No description found for return value of " .
1636 "No description found for return value of " .
1634 "'$declaration_name'\n";
1635 ++$warnings;
1637 "'$declaration_name'\n");
1636 }
1637}
1638
1639##
1640# takes a function prototype and the name of the current file being
1641# processed and spits out all the details stored in the global
1642# arrays/hashes.
1643sub dump_function($$) {

--- 65 unchanged lines hidden (view full) ---

1709 $prototype =~ m/^($type1)\s+($name)\s*$prototype_end/ ||
1710 $prototype =~ m/^($type2+)\s*($name)\s*$prototype_end/) {
1711 $return_type = $1;
1712 $declaration_name = $2;
1713 my $args = $3;
1714
1715 create_parameterlist($args, ',', $file, $declaration_name);
1716 } else {
1638 }
1639}
1640
1641##
1642# takes a function prototype and the name of the current file being
1643# processed and spits out all the details stored in the global
1644# arrays/hashes.
1645sub dump_function($$) {

--- 65 unchanged lines hidden (view full) ---

1711 $prototype =~ m/^($type1)\s+($name)\s*$prototype_end/ ||
1712 $prototype =~ m/^($type2+)\s*($name)\s*$prototype_end/) {
1713 $return_type = $1;
1714 $declaration_name = $2;
1715 my $args = $3;
1716
1717 create_parameterlist($args, ',', $file, $declaration_name);
1718 } else {
1717 print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
1719 emit_warning("${file}:$.", "cannot understand function prototype: '$prototype'\n");
1718 return;
1719 }
1720
1721 if ($identifier ne $declaration_name) {
1720 return;
1721 }
1722
1723 if ($identifier ne $declaration_name) {
1722 print STDERR "${file}:$.: warning: expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n";
1724 emit_warning("${file}:$.", "expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n");
1723 return;
1724 }
1725
1726 my $prms = join " ", @parameterlist;
1727 check_sections($file, $declaration_name, "function", $sectcheck, $prms);
1728
1729 # This check emits a lot of warnings at the moment, because many
1730 # functions don't have a 'Return' doc section. So until the number

--- 65 unchanged lines hidden (view full) ---

1796 if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
1797 $tracepointname = $2;
1798 }
1799 $tracepointname =~ s/^\s+//; #strip leading whitespace
1800 if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
1801 $tracepointargs = $1;
1802 }
1803 if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
1725 return;
1726 }
1727
1728 my $prms = join " ", @parameterlist;
1729 check_sections($file, $declaration_name, "function", $sectcheck, $prms);
1730
1731 # This check emits a lot of warnings at the moment, because many
1732 # functions don't have a 'Return' doc section. So until the number

--- 65 unchanged lines hidden (view full) ---

1798 if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
1799 $tracepointname = $2;
1800 }
1801 $tracepointname =~ s/^\s+//; #strip leading whitespace
1802 if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
1803 $tracepointargs = $1;
1804 }
1805 if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
1804 print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
1805 "$prototype\n";
1806 emit_warning("${file}:$.", "Unrecognized tracepoint format: \n".
1807 "$prototype\n");
1806 } else {
1807 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
1808 $identifier = "trace_$identifier";
1809 }
1810}
1811
1812sub syscall_munge() {
1813 my $void = 0;

--- 208 unchanged lines hidden (view full) ---

2022 $descr =~ s/\s+/ /g;
2023 $declaration_purpose = $descr;
2024 $state = STATE_BODY_MAYBE;
2025 } else {
2026 $declaration_purpose = "";
2027 }
2028
2029 if (!$is_kernel_comment) {
1808 } else {
1809 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
1810 $identifier = "trace_$identifier";
1811 }
1812}
1813
1814sub syscall_munge() {
1815 my $void = 0;

--- 208 unchanged lines hidden (view full) ---

2024 $descr =~ s/\s+/ /g;
2025 $declaration_purpose = $descr;
2026 $state = STATE_BODY_MAYBE;
2027 } else {
2028 $declaration_purpose = "";
2029 }
2030
2031 if (!$is_kernel_comment) {
2030 print STDERR "${file}:$.: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n";
2031 print STDERR $_;
2032 ++$warnings;
2032 emit_warning("${file}:$.", "This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n$_");
2033 $state = STATE_NORMAL;
2034 }
2035
2036 if (($declaration_purpose eq "") && $verbose) {
2033 $state = STATE_NORMAL;
2034 }
2035
2036 if (($declaration_purpose eq "") && $verbose) {
2037 print STDERR "${file}:$.: warning: missing initial short description on line:\n";
2038 print STDERR $_;
2039 ++$warnings;
2037 emit_warning("${file}:$.", "missing initial short description on line:\n$_");
2040 }
2041
2042 if ($identifier eq "" && $decl_type ne "enum") {
2038 }
2039
2040 if ($identifier eq "" && $decl_type ne "enum") {
2043 print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
2044 print STDERR $_;
2045 ++$warnings;
2041 emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n$_");
2046 $state = STATE_NORMAL;
2047 }
2048
2049 if ($verbose) {
2050 print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";
2051 }
2052 } else {
2042 $state = STATE_NORMAL;
2043 }
2044
2045 if ($verbose) {
2046 print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";
2047 }
2048 } else {
2053 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2054 " - I thought it was a doc line\n";
2055 ++$warnings;
2049 emit_warning("${file}:$.", "Cannot understand $_ on line $. - I thought it was a doc line\n");
2056 $state = STATE_NORMAL;
2057 }
2058}
2059
2060
2061#
2062# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
2063#
2064sub process_body($$) {
2065 my $file = shift;
2066
2067 # Until all named variable macro parameters are
2068 # documented using the bare name (`x`) rather than with
2069 # dots (`x...`), strip the dots:
2070 if ($section =~ /\w\.\.\.$/) {
2071 $section =~ s/\.\.\.$//;
2072
2073 if ($verbose) {
2050 $state = STATE_NORMAL;
2051 }
2052}
2053
2054
2055#
2056# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
2057#
2058sub process_body($$) {
2059 my $file = shift;
2060
2061 # Until all named variable macro parameters are
2062 # documented using the bare name (`x`) rather than with
2063 # dots (`x...`), strip the dots:
2064 if ($section =~ /\w\.\.\.$/) {
2065 $section =~ s/\.\.\.$//;
2066
2067 if ($verbose) {
2074 print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n";
2075 ++$warnings;
2068 emit_warning("${file}:$.", "Variable macro arguments should be documented without dots\n");
2076 }
2077 }
2078
2079 if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) {
2080 dump_section($file, $section, $contents);
2081 $section = $section_default;
2082 $new_start_line = $.;
2083 $contents = "";

--- 12 unchanged lines hidden (view full) ---

2096 $newsection = $section_return;
2097 } elsif ($newsection =~ m/^\@return$/) {
2098 # special: @return is a section, not a param description
2099 $newsection = $section_return;
2100 }
2101
2102 if (($contents ne "") && ($contents ne "\n")) {
2103 if (!$in_doc_sect && $verbose) {
2069 }
2070 }
2071
2072 if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) {
2073 dump_section($file, $section, $contents);
2074 $section = $section_default;
2075 $new_start_line = $.;
2076 $contents = "";

--- 12 unchanged lines hidden (view full) ---

2089 $newsection = $section_return;
2090 } elsif ($newsection =~ m/^\@return$/) {
2091 # special: @return is a section, not a param description
2092 $newsection = $section_return;
2093 }
2094
2095 if (($contents ne "") && ($contents ne "\n")) {
2096 if (!$in_doc_sect && $verbose) {
2104 print STDERR "${file}:$.: warning: contents before sections\n";
2105 ++$warnings;
2097 emit_warning("${file}:$.", "contents before sections\n");
2106 }
2107 dump_section($file, $section, $contents);
2108 $section = $section_default;
2109 }
2110
2111 $in_doc_sect = 1;
2112 $state = STATE_BODY;
2113 $contents = $newcontents;

--- 9 unchanged lines hidden (view full) ---

2123 } elsif (/$doc_end/) {
2124 if (($contents ne "") && ($contents ne "\n")) {
2125 dump_section($file, $section, $contents);
2126 $section = $section_default;
2127 $contents = "";
2128 }
2129 # look for doc_com + <text> + doc_end:
2130 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2098 }
2099 dump_section($file, $section, $contents);
2100 $section = $section_default;
2101 }
2102
2103 $in_doc_sect = 1;
2104 $state = STATE_BODY;
2105 $contents = $newcontents;

--- 9 unchanged lines hidden (view full) ---

2115 } elsif (/$doc_end/) {
2116 if (($contents ne "") && ($contents ne "\n")) {
2117 dump_section($file, $section, $contents);
2118 $section = $section_default;
2119 $contents = "";
2120 }
2121 # look for doc_com + <text> + doc_end:
2122 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2131 print STDERR "${file}:$.: warning: suspicious ending line: $_";
2132 ++$warnings;
2123 emit_warning("${file}:$.", "suspicious ending line: $_");
2133 }
2134
2135 $prototype = "";
2136 $state = STATE_PROTO;
2137 $brcount = 0;
2138 $new_start_line = $. + 1;
2139 } elsif (/$doc_content/) {
2140 if ($1 eq "") {

--- 27 unchanged lines hidden (view full) ---

2168 }
2169 }
2170 $cont =~ s/^$leading_space//;
2171 }
2172 $contents .= $cont . "\n";
2173 }
2174 } else {
2175 # i dont know - bad line? ignore.
2124 }
2125
2126 $prototype = "";
2127 $state = STATE_PROTO;
2128 $brcount = 0;
2129 $new_start_line = $. + 1;
2130 } elsif (/$doc_content/) {
2131 if ($1 eq "") {

--- 27 unchanged lines hidden (view full) ---

2159 }
2160 }
2161 $cont =~ s/^$leading_space//;
2162 }
2163 $contents .= $cont . "\n";
2164 }
2165 } else {
2166 # i dont know - bad line? ignore.
2176 print STDERR "${file}:$.: warning: bad line: $_";
2177 ++$warnings;
2167 emit_warning("${file}:$.", "bad line: $_");
2178 }
2179}
2180
2181
2182#
2183# STATE_PROTO: reading a function/whatever prototype.
2184#
2185sub process_proto($$) {

--- 77 unchanged lines hidden (view full) ---

2263 if ($inline_doc_state == STATE_INLINE_TEXT) {
2264 $contents .= $1 . "\n";
2265 # nuke leading blank lines
2266 if ($contents =~ /^\s*$/) {
2267 $contents = "";
2268 }
2269 } elsif ($inline_doc_state == STATE_INLINE_NAME) {
2270 $inline_doc_state = STATE_INLINE_ERROR;
2168 }
2169}
2170
2171
2172#
2173# STATE_PROTO: reading a function/whatever prototype.
2174#
2175sub process_proto($$) {

--- 77 unchanged lines hidden (view full) ---

2253 if ($inline_doc_state == STATE_INLINE_TEXT) {
2254 $contents .= $1 . "\n";
2255 # nuke leading blank lines
2256 if ($contents =~ /^\s*$/) {
2257 $contents = "";
2258 }
2259 } elsif ($inline_doc_state == STATE_INLINE_NAME) {
2260 $inline_doc_state = STATE_INLINE_ERROR;
2271 print STDERR "${file}:$.: warning: ";
2272 print STDERR "Incorrect use of kernel-doc format: $_";
2273 ++$warnings;
2261 emit_warning("${file}:$.", "Incorrect use of kernel-doc format: $_");
2274 }
2275 }
2276}
2277
2278
2279sub process_file($) {
2280 my $file;
2281 my $initial_section_counter = $section_counter;

--- 32 unchanged lines hidden (view full) ---

2314 process_docblock($file, $_);
2315 }
2316 }
2317
2318 # Make sure we got something interesting.
2319 if ($initial_section_counter == $section_counter && $
2320 output_mode ne "none") {
2321 if ($output_selection == OUTPUT_INCLUDE) {
2262 }
2263 }
2264}
2265
2266
2267sub process_file($) {
2268 my $file;
2269 my $initial_section_counter = $section_counter;

--- 32 unchanged lines hidden (view full) ---

2302 process_docblock($file, $_);
2303 }
2304 }
2305
2306 # Make sure we got something interesting.
2307 if ($initial_section_counter == $section_counter && $
2308 output_mode ne "none") {
2309 if ($output_selection == OUTPUT_INCLUDE) {
2322 print STDERR "${file}:1: warning: '$_' not found\n"
2310 emit_warning("${file}:1", "'$_' not found\n")
2323 for keys %function_table;
2324 }
2325 else {
2311 for keys %function_table;
2312 }
2313 else {
2326 print STDERR "${file}:1: warning: no structured comments found\n";
2314 emit_warning("${file}:1", "no structured comments found\n");
2327 }
2328 }
2329 close IN_FILE;
2330}
2331
2332
2333if ($output_mode eq "rst") {
2334 get_sphinx_version() if (!$sphinx_major);

--- 169 unchanged lines hidden --- 		2315 }
2316 }
2317 close IN_FILE;
2318}
2319
2320
2321if ($output_mode eq "rst") {
2322 get_sphinx_version() if (!$sphinx_major);

--- 169 unchanged lines hidden ---