Lines Matching +full:- +full:- +full:enable +full:- +full:werror
2 # SPDX-License-Identifier: GPL-2.0-only
10 ## Copyright (C) 2005-2012 Randy Dunlap ##
19 # 18/01/2001 - Cleanups
22 # -- huggie@earth.li
24 # 27/06/2001 - Allowed whitespace after initial "/**" and
26 # -- Christian Kreibich <ck@whoop.org>
29 # - add perldoc documentation
30 # - Look more closely at some of the scarier bits :)
32 # 26/05/2001 - Support for separate source and object trees.
36 # 23/09/2001 - Added support for typedefs, structs, enums and unions
39 # -- Tim Jansen <tim@tjansen.de>
41 # 25/07/2012 - Added support for HTML5
42 # -- Dan Luedtke <mail@danrl.de>
52 Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
55 -man Output troff manual page format. This is the default.
56 -rst Output reStructuredText format.
57 -none Do not output documentation, only warnings.
61 -sphinx-version Use the ReST C domain dialect compatible with an
63 If not specified, kernel-doc will auto-detect using
64 the sphinx-build version found on PATH.
67 -export Only output documentation for symbols that have been
69 in any input FILE or -export-file FILE.
70 -internal Only output documentation for symbols that have NOT been
72 in any input FILE or -export-file FILE.
73 -function NAME Only output documentation for the given function(s)
76 -nosymbol NAME Exclude the specified symbols from the output
80 -no-doc-sections Do not output DOC: sections.
81 -enable-lineno Enable output of #define LINENO lines. Only works with
83 -export-file FILE Specify an additional FILE in which to look for
85 -export or -internal. May be specified multiple times.
88 -v Verbose output, more warnings and other information.
89 -h Print this help.
90 -Werror Treat warnings as errors.
102 # * function_name(:)? (- short description)?
119 # * my_function - does my stuff
127 # * my_function - does my stuff
140 # * struct my_struct - short description
159 # * struct my_struct - short description
183 # A non-void function should have a "Return:" section describing the return
185 # Example-sections should contain the string EXAMPLE so that they are marked
190 # * user_function - function that can only be called in user context
204 # 'funcname()' - function
205 # '$ENVVAR' - environmental variable
206 # '&struct_name' - name of a structure (up to two words including 'struct')
207 # '&struct_name.member' - name of a structure member
208 # '@parameter' - name of a parameter
209 # '%CONST' - name of a constant.
210 # '``LITERAL``' - literal string without any spaces on it.
220 my $type_constant2 = '\%([-_\w]+)';
222 my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
223 my $type_param_ref = '([\!]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
225 my $type_fp_param2 = '\@(\w+->\S+)\(\)'; # Special RST handling for structs with func ptr params
229 my $type_typedef = '#(([A-Z][_\w]*))';
231 my $type_member = '#([_\w]+)(\.|->)([_\w]+)';
254 # rst-mode
275 if ($#ARGV == -1) {
285 my $Werror = 0;
298 OUTPUT_INTERNAL => 3, # output non-exported symbols
307 (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
333 $Werror = "$ENV{'KDOC_WERROR'}";
339 if ($kcflags =~ /Werror/) {
340 $Werror = 1;
345 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
346 # https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
358 STATE_BODY_MAYBE => 2, # body - or maybe more description
375 STATE_INLINE_ERROR => 4, # error - Comment without header was found.
377 # proper kernel-doc and ignore the rest.
420 my $undescribed = "-- undescribed --";
424 while ($ARGV[0] =~ m/^--?(.*)/) {
449 } elsif ($cmd eq "internal") { # only non-exported symbols
452 } elsif ($cmd eq "export-file") {
457 } elsif ($cmd eq "Werror") {
458 $Werror = 1;
461 } elsif ($cmd eq 'no-doc-sections') {
463 } elsif ($cmd eq 'enable-lineno') {
465 } elsif ($cmd eq 'show-not-found') {
466 $show_not_found = 1; # A no-op but don't fail
467 } elsif ($cmd eq "sphinx-version") {
497 return "$_/$_[0]" if(-x "$_/$_[0]");
505 my $cmd = "sphinx-build";
507 my $cmd = "sphinx-build3";
518 open IN, "$cmd --version 2>&1 |";
520 if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {
613 'content-only' => ($output_selection != OUTPUT_ALL), });
672 print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
689 # pointer-to-function
723 print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
763 print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
798 print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
845 # Apply the RST highlights to a sub-block of text.
859 my $sphinx_cblock = '^\.\.\ +code-block::';
877 # If this is the first non-blank line in a literal
968 # pointer-to-function
1175 # generic output function - calls the right one based on current output mode.
1201 …|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/)…
1212 $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)/ /gi;
1223 $members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
1245 # pointer-to-function
1315 $level-- if ($clause =~ m/(\})/ && $level > 1);
1530 # pointer-to-function
1566 if ($type ne "") { # skip unnamed bit-fields
1664 $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
1749 $prototype =~ s/QEMU_[A-Z_]+ +//;
1763 # - parport_register_device (function pointer parameters)
1764 # - atomic_set (macro)
1765 # - pci_match_device, __copy_to_user (long return type)
1767 if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
1768 # This is an object-like macro, it has no return type and no parameter
1770 # Function-like macros are not allowed to have spaces between
1775 } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1776 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1777 $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1778 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1779 $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1780 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1781 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1782 $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1783 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1784 $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1785 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1786 $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1787 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1788 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1789 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1790 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1791 $prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
1891 ## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
1904 # now delete all of the odd-number commas in $prototype
1909 $len = 0; # skip the for-loop
1925 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1963 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1977 ($2 eq '}') && $brcount--;
2043 # STATE_NAME: Looking for the "name - description" line
2063 if (/\s*([\w\s]+?)(\s*-|:)/) {
2073 if (/[-:](.*)/) {
2108 " - I thought it was a doc line\n";
2184 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2229 # i dont know - bad line? ignore.
2326 print STDERR "Incorrect use of kernel-doc format: $_";
2354 while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
2437 if ($Werror && $warnings) {