kernel-doc (8aaf297a0dd66d4fac215af24ece8dea091079bc) kernel-doc (56b0f453db74207633019f83758b4c11c66b75d0)
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]
26 kernel-doc [-h] [-v] [-Werror] [-Wall] [-Wreturn] [-Wshort-description] [-Wcontents-before-sections]
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;
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
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
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
190if (defined($ENV{'KDOC_WERROR'})) {
191 $Werror = "$ENV{'KDOC_WERROR'}";
192}
196if (defined($ENV{'KDOC_WERROR'})) {
197 $Werror = "$ENV{'KDOC_WERROR'}";
198}
199# other environment variables are converted to command-line
200# arguments in cmd_checkdoc in the build system
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;
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;
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;
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

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

1743 }
1744
1745 my $prms = join " ", @parameterlist;
1746 check_sections($file, $declaration_name, "function", $sectcheck, $prms);
1747
1748 # This check emits a lot of warnings at the moment, because many
1749 # functions don't have a 'Return' doc section. So until the number
1750 # of warnings goes sufficiently down, the check is only performed in
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

--- 1414 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
1751 # verbose mode.
1769 # -Wreturn mode.
1752 # TODO: always perform the check.
1770 # TODO: always perform the check.
1753 if ($verbose && !$noret) {
1771 if ($Wreturn && !$noret) {
1754 check_return_section($file, $declaration_name, $return_type);
1755 }
1756
1757 # The function parser can be called with a typedef parameter.
1758 # Handle it.
1759 if ($return_type =~ /typedef/) {
1760 output_declaration($declaration_name,
1761 'function',

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

2049 $declaration_purpose = "";
2050 }
2051
2052 if (!$is_kernel_comment) {
2053 emit_warning("${file}:$.", "This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n$_");
2054 $state = STATE_NORMAL;
2055 }
2056
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
2057 if (($declaration_purpose eq "") && $verbose) {
2075 if (($declaration_purpose eq "") && $Wshort_desc) {
2058 emit_warning("${file}:$.", "missing initial short description on line:\n$_");
2059 }
2060
2061 if ($identifier eq "" && $decl_type ne "enum") {
2062 emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n$_");
2063 $state = STATE_NORMAL;
2064 }
2065

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

2098 } elsif ($newsection =~ m/^returns?$/i) {
2099 $newsection = $section_return;
2100 } elsif ($newsection =~ m/^\@return$/) {
2101 # special: @return is a section, not a param description
2102 $newsection = $section_return;
2103 }
2104
2105 if (($contents ne "") && ($contents ne "\n")) {
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")) {
2106 if (!$in_doc_sect && $verbose) {
2124 if (!$in_doc_sect && $Wcontents_before_sections) {
2107 emit_warning("${file}:$.", "contents before sections\n");
2108 }
2109 dump_section($file, $section, $contents);
2110 $section = $section_default;
2111 }
2112
2113 $in_doc_sect = 1;
2114 $state = STATE_BODY;

--- 386 unchanged lines hidden --- 		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 ---