Lines Matching +full:a +full:- +full:za +full:- +full:z0 +full:- +full:9 +full:-
2 # SPDX-License-Identifier: GPL-2.0
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.
60 -export Only output documentation for symbols that have been
62 in any input FILE or -export-file FILE.
63 -internal Only output documentation for symbols that have NOT been
65 in any input FILE or -export-file FILE.
66 -function NAME Only output documentation for the given function(s)
69 -nofunction NAME Do NOT output documentation for the given function(s);
74 -no-doc-sections Do not output DOC: sections.
75 -enable-lineno Enable output of #define LINENO lines. Only works with
77 -export-file FILE Specify an additional FILE in which to look for
79 -export or -internal. May be specified multiple times.
82 -v Verbose output, more warnings and other information.
83 -h Print this help.
95 # * function_name(:)? (- short description)?
97 # (* a blank line)?
108 # If the Description: header tag is omitted, then there must be a blank line
112 # * my_function - does my stuff
120 # * my_function - does my stuff
133 # * struct my_struct - short description
134 # * @a: first member
140 # int a;
152 # * struct my_struct - short description
153 # * @a: first member
159 # int a;
176 # A non-void function should have a "Return:" section describing the return
178 # Example-sections should contain the string EXAMPLE so that they are marked
183 # * user_function - function that can only be called in user context
184 # * @a: some argument
197 # 'funcname()' - function
198 # '$ENVVAR' - environmental variable
199 # '&struct_name' - name of a structure (up to two words including 'struct')
200 # '&struct_name.member' - name of a structure member
201 # '@parameter' - name of a parameter
202 # '%CONST' - name of a constant.
203 # '``LITERAL``' - literal string without any spaces on it.
213 my $type_constant2 = '\%([-_\w]+)';
215 my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
222 my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
244 # rst-mode
264 if ($#ARGV == -1) {
285 OUTPUT_INTERNAL => 4, # output non-exported symbols
294 (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
318 # Generated docbook code is inserted in a template at a point where
319 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
320 # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
321 # We keep track of number of generated entries and generate a dummy
332 STATE_BODY_MAYBE => 2, # body - or maybe more description
348 STATE_INLINE_ERROR => 4, # error - Comment without header was found.
349 # Spit a warning as it's not
350 # proper kernel-doc and ignore the rest.
363 # @params and a strictly limited set of supported section names
393 my $undescribed = "-- undescribed --";
397 while ($ARGV[0] =~ m/^--?(.*)/) {
423 } elsif ($cmd eq "internal") { # only non-exported symbols
426 } elsif ($cmd eq "export-file") {
433 } elsif ($cmd eq 'no-doc-sections') {
435 } elsif ($cmd eq 'enable-lineno') {
437 } elsif ($cmd eq 'show-not-found') {
438 $show_not_found = 1; # A no-op but don't fail
523 'content-only' => ($output_selection != OUTPUT_ALL), });
530 # parameterdescs, a hash.
579 …print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" …
582 print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
599 # pointer-to-function
630 print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
633 print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
670 …print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \…
673 print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
705 print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
708 print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
721 print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
736 # to duplicate a header already in the template file.
753 # Apply the RST highlights to a sub-block of text.
767 my $sphinx_cblock = '^\.\.\ +code-block::';
779 # If we're in a literal block, see if we should drop out
785 # If this is the first non-blank line in a literal
802 # Not in a literal block (or just dropped out)
855 # pointer-to-function
1039 # generic output function - calls the right one based on current output mode.
1048 # takes a declaration (struct, union, enum, typedef) and
1065 …if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|__attribute__\s*\(\([a-z0-9,_\…
1076 $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)//gi;
1083 $members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
1105 # pointer-to-function
1175 $level-- if ($clause =~ m/(\})/ && $level > 1);
1378 # Treat preprocessor directive as a typeless variable just to fill
1383 # pointer-to-function
1418 if ($type ne "") { # skip unnamed bit-fields
1486 # this fixes a problem where check_sections() cannot find
1487 # a parameter like "addr[6 + 2]" because it actually appears
1491 # "[blah" in a parameter string;
1511 $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
1512 # ignore array size in a parameter string;
1539 # Checks the section describing the return value of a function.
1545 # Ignore an empty return type (It's a macro)
1546 # Ignore functions with a "void" return type. (But don't ignore "void *")
1561 # takes a function prototype and the name of the current file being
1594 # 1. Return type (may be nothing if we're looking at a macro)
1603 # If you mess with these regexps, it's a good idea to check that
1605 # - parport_register_device (function pointer parameters)
1606 # - atomic_set (macro)
1607 # - pci_match_device, __copy_to_user (long return type)
1609 if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
1610 # This is an object-like macro, it has no return type and no parameter
1612 # Function-like macros are not allowed to have spaces between
1617 } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1618 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1619 $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1620 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1621 $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1622 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1623 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1624 $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1625 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1626 $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1627 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1628 $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1629 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1630 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1631 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1632 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1633 $prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
1647 # This check emits a lot of warnings at the moment, because many
1648 # functions don't have a 'Return' doc section. So until the number
1715 ## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
1728 # now delete all of the odd-number commas in $prototype
1729 # so that arg types & arg names don't have a comma between them
1733 $len = 0; # skip the for-loop
1749 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1782 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1796 ($2 eq '}') && $brcount--;
1861 # STATE_NAME: Looking for the "name - description" line
1881 if (/\s*([\w\s]+?)(\(\))?\s*-/) {
1891 if (/-(.*)/) {
1926 " - I thought it was a doc line\n";
1934 # STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
1951 # special: @return is a section, not a param description
1983 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
1992 # miguel-style comment kludge, look for blank lines after
2024 # i dont know - bad line? ignore.
2032 # STATE_PROTO: reading a function/whatever prototype.
2057 # STATE_DOCBLOCK: within a DOC: block.
2084 # STATE_INLINE: docbook comments within a prototype.
2089 # First line (state 1) needs to be a @parameter
2121 print STDERR "Incorrect use of kernel-doc format: $_";
2149 while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
2182 # generate a sequence of code that will splice in highlighting information