kernel-doc (3fbff91afbf0148e937b8718ed865b073c587d9f) kernel-doc (e27cb89a22ada4e3e7bee1567a8daa1fb2260b78)
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> ##

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

18use Pod::Usage qw/pod2usage/;
19
20=head1 NAME
21
22kernel-doc - Print formatted kernel documentation to stdout
23
24=head1 SYNOPSIS
25
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> ##

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

18use Pod::Usage qw/pod2usage/;
19
20=head1 NAME
21
22kernel-doc - Print formatted kernel documentation to stdout
23
24=head1 SYNOPSIS
25
26 kernel-doc [-h] [-v] [-Werror] [-Wall] [-Wreturn] [-Wshort-description] [-Wcontents-before-sections]
26 kernel-doc [-h] [-v] [-Werror]
27 [ -man |
28 -rst [-sphinx-version VERSION] [-enable-lineno] |
29 -none
30 ]
31 [
32 -export |
33 -internal |
34 [-function NAME] ... |

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

59my $warnings = 0;
60my $anon_struct_union = 0;
61
62# match expressions used to find embedded type information
63my $type_constant = '\b``([^\`]+)``\b';
64my $type_constant2 = '\%([-_\w]+)';
65my $type_func = '(\w+)\(\)';
66my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
27 [ -man |
28 -rst [-sphinx-version VERSION] [-enable-lineno] |
29 -none
30 ]
31 [
32 -export |
33 -internal |
34 [-function NAME] ... |

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

59my $warnings = 0;
60my $anon_struct_union = 0;
61
62# match expressions used to find embedded type information
63my $type_constant = '\b``([^\`]+)``\b';
64my $type_constant2 = '\%([-_\w]+)';
65my $type_func = '(\w+)\(\)';
66my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
67my $type_param_ref = '([\!~]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
67my $type_param_ref = '([\!]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
68my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
69my $type_fp_param2 = '\@(\w+->\S+)\(\)'; # Special RST handling for structs with func ptr params
70my $type_env = '(\$\w+)';
71my $type_enum = '\&(enum\s*([_\w]+))';
72my $type_struct = '\&(struct\s*([_\w]+))';
73my $type_typedef = '\&(typedef\s*([_\w]+))';
74my $type_union = '\&(union\s*([_\w]+))';
75my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';

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

128
129my $kernelversion;
130my ($sphinx_major, $sphinx_minor, $sphinx_patch);
131
132my $dohighlight = "";
133
134my $verbose = 0;
135my $Werror = 0;
68my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
69my $type_fp_param2 = '\@(\w+->\S+)\(\)'; # Special RST handling for structs with func ptr params
70my $type_env = '(\$\w+)';
71my $type_enum = '\&(enum\s*([_\w]+))';
72my $type_struct = '\&(struct\s*([_\w]+))';
73my $type_typedef = '\&(typedef\s*([_\w]+))';
74my $type_union = '\&(union\s*([_\w]+))';
75my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';

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

128
129my $kernelversion;
130my ($sphinx_major, $sphinx_minor, $sphinx_patch);
131
132my $dohighlight = "";
133
134my $verbose = 0;
135my $Werror = 0;
136my $Wreturn = 0;
137my $Wshort_desc = 0;
138my $Wcontents_before_sections = 0;
139my $output_mode = "rst";
140my $output_preformatted = 0;
141my $no_doc_sections = 0;
142my $enable_lineno = 0;
143my @highlights = @highlights_rst;
144my $blankline = $blankline_rst;
145my $modulename = "Kernel API";
146

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

185if (defined($ENV{'KCFLAGS'})) {
186 my $kcflags = "$ENV{'KCFLAGS'}";
187
188 if ($kcflags =~ /Werror/) {
189 $Werror = 1;
190 }
191}
192
136my $output_mode = "rst";
137my $output_preformatted = 0;
138my $no_doc_sections = 0;
139my $enable_lineno = 0;
140my @highlights = @highlights_rst;
141my $blankline = $blankline_rst;
142my $modulename = "Kernel API";
143

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

182if (defined($ENV{'KCFLAGS'})) {
183 my $kcflags = "$ENV{'KCFLAGS'}";
184
185 if ($kcflags =~ /Werror/) {
186 $Werror = 1;
187 }
188}
189
193# reading this variable is for backwards compat just in case
194# someone was calling it with the variable from outside the
195# kernel's build system
196if (defined($ENV{'KDOC_WERROR'})) {
197 $Werror = "$ENV{'KDOC_WERROR'}";
198}
190if (defined($ENV{'KDOC_WERROR'})) {
191 $Werror = "$ENV{'KDOC_WERROR'}";
192}
199# other environment variables are converted to command-line
200# arguments in cmd_checkdoc in the build system
201
202# Generated docbook code is inserted in a template at a point where
203# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
204# https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
205# We keep track of number of generated entries and generate a dummy
206# if needs be to ensure the expanded template can be postprocessed
207# into html.
208my $section_counter = 0;

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

321 %function_table = ();
322 } elsif ($cmd eq "export-file") {
323 my $file = shift @ARGV;
324 push(@export_file_list, $file);
325 } elsif ($cmd eq "v") {
326 $verbose = 1;
327 } elsif ($cmd eq "Werror") {
328 $Werror = 1;
193
194# Generated docbook code is inserted in a template at a point where
195# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
196# https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
197# We keep track of number of generated entries and generate a dummy
198# if needs be to ensure the expanded template can be postprocessed
199# into html.
200my $section_counter = 0;

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

313 %function_table = ();
314 } elsif ($cmd eq "export-file") {
315 my $file = shift @ARGV;
316 push(@export_file_list, $file);
317 } elsif ($cmd eq "v") {
318 $verbose = 1;
319 } elsif ($cmd eq "Werror") {
320 $Werror = 1;
329 } elsif ($cmd eq "Wreturn") {
330 $Wreturn = 1;
331 } elsif ($cmd eq "Wshort-desc") {
332 $Wshort_desc = 1;
333 } elsif ($cmd eq "Wcontents-before-sections") {
334 $Wcontents_before_sections = 1;
335 } elsif ($cmd eq "Wall") {
336 $Wreturn = 1;
337 $Wshort_desc = 1;
338 $Wcontents_before_sections = 1;
339 } elsif (($cmd eq "h") || ($cmd eq "help")) {
340 pod2usage(-exitval => 0, -verbose => 2);
341 } elsif ($cmd eq 'no-doc-sections') {
342 $no_doc_sections = 1;
343 } elsif ($cmd eq 'enable-lineno') {
344 $enable_lineno = 1;
345 } elsif ($cmd eq 'show-not-found') {
346 $show_not_found = 1; # A no-op but don't fail

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

1314 die("Please add the new output type at show_warnings()");
1315}
1316
1317sub dump_enum($$) {
1318 my $x = shift;
1319 my $file = shift;
1320 my $members;
1321
321 } elsif (($cmd eq "h") || ($cmd eq "help")) {
322 pod2usage(-exitval => 0, -verbose => 2);
323 } elsif ($cmd eq 'no-doc-sections') {
324 $no_doc_sections = 1;
325 } elsif ($cmd eq 'enable-lineno') {
326 $enable_lineno = 1;
327 } elsif ($cmd eq 'show-not-found') {
328 $show_not_found = 1; # A no-op but don't fail

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

1296 die("Please add the new output type at show_warnings()");
1297}
1298
1299sub dump_enum($$) {
1300 my $x = shift;
1301 my $file = shift;
1302 my $members;
1303
1304 # ignore members marked private:
1305 $x =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
1306 $x =~ s/\/\*\s*private:.*}/}/gosi;
1322
1323 $x =~ s@/\*.*?\*/@@gos; # strip comments.
1324 # strip #define macros inside enums
1325 $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
1326
1327 if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;/) {
1328 $declaration_name = $2;
1329 $members = $1;

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

1761 }
1762
1763 my $prms = join " ", @parameterlist;
1764 check_sections($file, $declaration_name, "function", $sectcheck, $prms);
1765
1766 # This check emits a lot of warnings at the moment, because many
1767 # functions don't have a 'Return' doc section. So until the number
1768 # of warnings goes sufficiently down, the check is only performed in
1307
1308 $x =~ s@/\*.*?\*/@@gos; # strip comments.
1309 # strip #define macros inside enums
1310 $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
1311
1312 if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;/) {
1313 $declaration_name = $2;
1314 $members = $1;

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

1746 }
1747
1748 my $prms = join " ", @parameterlist;
1749 check_sections($file, $declaration_name, "function", $sectcheck, $prms);
1750
1751 # This check emits a lot of warnings at the moment, because many
1752 # functions don't have a 'Return' doc section. So until the number
1753 # of warnings goes sufficiently down, the check is only performed in
1769 # -Wreturn mode.
1754 # verbose mode.
1770 # TODO: always perform the check.
1755 # TODO: always perform the check.
1771 if ($Wreturn && !$noret) {
1756 if ($verbose && !$noret) {
1772 check_return_section($file, $declaration_name, $return_type);
1773 }
1774
1775 # The function parser can be called with a typedef parameter.
1776 # Handle it.
1777 if ($return_type =~ /typedef/) {
1778 output_declaration($declaration_name,
1779 'function',

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

2067 $declaration_purpose = "";
2068 }
2069
2070 if (!$is_kernel_comment) {
2071 emit_warning("${file}:$.", "This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n$_");
2072 $state = STATE_NORMAL;
2073 }
2074
1757 check_return_section($file, $declaration_name, $return_type);
1758 }
1759
1760 # The function parser can be called with a typedef parameter.
1761 # Handle it.
1762 if ($return_type =~ /typedef/) {
1763 output_declaration($declaration_name,
1764 'function',

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

2052 $declaration_purpose = "";
2053 }
2054
2055 if (!$is_kernel_comment) {
2056 emit_warning("${file}:$.", "This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n$_");
2057 $state = STATE_NORMAL;
2058 }
2059
2075 if (($declaration_purpose eq "") && $Wshort_desc) {
2060 if (($declaration_purpose eq "") && $verbose) {
2076 emit_warning("${file}:$.", "missing initial short description on line:\n$_");
2077 }
2078
2079 if ($identifier eq "" && $decl_type ne "enum") {
2080 emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n$_");
2081 $state = STATE_NORMAL;
2082 }
2083

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

2116 } elsif ($newsection =~ m/^returns?$/i) {
2117 $newsection = $section_return;
2118 } elsif ($newsection =~ m/^\@return$/) {
2119 # special: @return is a section, not a param description
2120 $newsection = $section_return;
2121 }
2122
2123 if (($contents ne "") && ($contents ne "\n")) {
2061 emit_warning("${file}:$.", "missing initial short description on line:\n$_");
2062 }
2063
2064 if ($identifier eq "" && $decl_type ne "enum") {
2065 emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n$_");
2066 $state = STATE_NORMAL;
2067 }
2068

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

2101 } elsif ($newsection =~ m/^returns?$/i) {
2102 $newsection = $section_return;
2103 } elsif ($newsection =~ m/^\@return$/) {
2104 # special: @return is a section, not a param description
2105 $newsection = $section_return;
2106 }
2107
2108 if (($contents ne "") && ($contents ne "\n")) {
2124 if (!$in_doc_sect && $Wcontents_before_sections) {
2109 if (!$in_doc_sect && $verbose) {
2125 emit_warning("${file}:$.", "contents before sections\n");
2126 }
2127 dump_section($file, $section, $contents);
2128 $section = $section_default;
2129 }
2130
2131 $in_doc_sect = 1;
2132 $state = STATE_BODY;

--- 386 unchanged lines hidden --- 		2110 emit_warning("${file}:$.", "contents before sections\n");
2111 }
2112 dump_section($file, $section, $contents);
2113 $section = $section_default;
2114 }
2115
2116 $in_doc_sect = 1;
2117 $state = STATE_BODY;

--- 386 unchanged lines hidden ---