Lines Matching +full:a +full:- +full:za +full:- +full:z0 +full:- +full:9
2 # SPDX-License-Identifier: GPL-2.0
10 ## Copyright (C) 2005-2012 Randy Dunlap ##
22 kernel-doc - Print formatted kernel documentation to stdout
26 …kernel-doc [-h] [-v] [-Werror] [-Wall] [-Wreturn] [-Wshort-description] [-Wcontents-before-section…
27 [ -man |
28 -rst [-sphinx-version VERSION] [-enable-lineno] |
29 -none
32 -export |
33 -internal |
34 [-function NAME] ... |
35 [-nosymbol NAME] ...
37 [-no-doc-sections]
38 [-export-file FILE] ...
41 Run `kernel-doc -h` for details.
50 See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
64 my $type_constant2 = '\%([-_\w]+)';
66 my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
67 my $type_param_ref = '([\!~]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
69 my $type_fp_param2 = '\@(\w+->\S+)\(\)'; # Special RST handling for structs with func ptr params
75 my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
98 # rst-mode
119 if ($#ARGV == -1) {
121 -message => "No arguments!\n",
122 -exitval => 1,
123 -verbose => 99,
124 -sections => 'SYNOPSIS',
125 -output => \*STDERR,
151 OUTPUT_INTERNAL => 3, # output non-exported symbols
160 (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
199 # other environment variables are converted to command-line
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
216 STATE_BODY_MAYBE => 2, # body - or maybe more description
218 STATE_BODY_WITH_BLANK_LINE => 4, # the body, which has a blank line
233 STATE_INLINE_ERROR => 4, # error - Comment without header was found.
234 # Spit a warning as it's not
235 # proper kernel-doc and ignore the rest.
243 # Name of the kernel-doc identifier for non-DOC markups
251 # @params and a strictly limited set of supported section names
255 # @{section-name}:
269 my $attribute = qr{__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)}i;
290 my $undescribed = "-- undescribed --";
294 while ($ARGV[0] =~ m/^--?(.*)/) {
319 } elsif ($cmd eq "internal") { # only non-exported symbols
322 } elsif ($cmd eq "export-file") {
331 } elsif ($cmd eq "Wshort-desc") {
333 } elsif ($cmd eq "Wcontents-before-sections") {
340 pod2usage(-exitval => 0, -verbose => 2);
341 } elsif ($cmd eq 'no-doc-sections') {
343 } elsif ($cmd eq 'enable-lineno') {
345 } elsif ($cmd eq 'show-not-found') {
346 $show_not_found = 1; # A no-op but don't fail
347 } elsif ($cmd eq "sphinx-version") {
367 -message => "Argument unknown!\n",
368 -exitval => 1,
369 -verbose => 99,
370 -sections => 'SYNOPSIS',
371 -output => \*STDERR,
376 -message => "FILE argument missing\n",
377 -exitval => 1,
378 -verbose => 99,
379 -sections => 'SYNOPSIS',
380 -output => \*STDERR,
392 return "$_/$_[0]" if(-x "$_/$_[0]");
400 my $cmd = "sphinx-build";
402 my $cmd = "sphinx-build3";
413 open IN, "$cmd --version 2>&1 |";
415 if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {
421 # Sphinx 1.2.x uses a different format
514 'content-only' => ($output_selection != OUTPUT_ALL), });
521 # parameterdescs, a hash.
570 …print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" …
573 print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
590 # pointer-to-function
621 print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
624 print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
661 …print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \…
664 print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
696 print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
699 print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
712 print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
727 # to duplicate a header already in the template file.
747 # Apply the RST highlights to a sub-block of text.
761 my $sphinx_cblock = '^\.\.\ +code-block::';
773 # If we're in a literal block, see if we should drop out
779 # If this is the first non-blank line in a literal
796 # Not in a literal block (or just dropped out)
870 # pointer-to-function
889 # Put our descriptive text into a container (thus an HTML <div>) to help
1089 # generic output function - calls the right one based on current output mode.
1098 # takes a declaration (struct, union, enum, typedef) and
1151 # - first eat non-declaration parameters and rewrite for final match
1152 # - then remove macro, outer parens, and trailing semicolon
1164 $members =~ s/DECLARE_HASHTABLE\s*\($args,\s*$args\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
1191 # pointer-to-function
1261 $level-- if ($clause =~ m/(\})/ && $level > 1);
1345 emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n");
1498 # Treat preprocessor directive as a typeless variable just to fill
1503 # pointer-to-function
1539 if ($type ne "") { # skip unnamed bit-fields
1610 # this fixes a problem where check_sections() cannot find
1611 # a parameter like "addr[6 + 2]" because it actually appears
1615 # "[blah" in a parameter string;
1636 # ignore array size in a parameter string;
1662 # Checks the section describing the return value of a function.
1668 # Ignore an empty return type (It's a macro)
1669 # Ignore functions with a "void" return type. (But don't ignore "void *")
1683 # takes a function prototype and the name of the current file being
1724 # 1. Return type (may be nothing if we're looking at a macro)
1733 # If you mess with these regexps, it's a good idea to check that
1735 # - parport_register_device (function pointer parameters)
1736 # - atomic_set (macro)
1737 # - pci_match_device, __copy_to_user (long return type)
1738 my $name = qr{[a-zA-Z0-9_~:]+};
1746 # This is an object-like macro, it has no return type and no parameter
1748 # Function-like macros are not allowed to have spaces between
1774 # This check emits a lot of warnings at the moment, because many
1775 # functions don't have a 'Return' doc section. So until the number
1777 # -Wreturn mode.
1783 # The function parser can be called with a typedef parameter.
1861 ## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
1874 # now delete all of the odd-number commas in $prototype
1875 # so that arg types & arg names don't have a comma between them
1879 $len = 0; # skip the for-loop
1895 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1933 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1947 ($2 eq '}') && $brcount--;
2017 # STATE_NAME: Looking for the "name - description" line
2037 # test for pointer declaration type, foo * bar() - desc
2040 my $decl_end = qr{[-:].*};
2049 # Look for foo() or static void foo() - description; or misspelt
2066 if (/[-:](.*)/) {
2079 ….", "This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide…
2088 emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n$_");
2096 emit_warning("${file}:$.", "Cannot understand $_ on line $. - I thought it was a doc line\n");
2103 # STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
2127 # special: @return is a section, not a param description
2158 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2202 # i dont know - bad line? ignore.
2209 # STATE_PROTO: reading a function/whatever prototype.
2234 # STATE_DOCBLOCK: within a DOC: block.
2261 # STATE_INLINE: docbook comments within a prototype.
2266 # First line (state 1) needs to be a @parameter
2297 emit_warning("${file}:$.", "Incorrect use of kernel-doc format: $_");
2324 while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
2363 # generate a sequence of code that will splice in highlighting information
2422 =item -man
2426 =item -rst
2430 =item -none
2442 =item -sphinx-version VERSION
2444 Use the ReST C domain dialect compatible with a specific Sphinx Version.
2446 If not specified, kernel-doc will auto-detect using the sphinx-build version
2455 =item -export
2458 EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE.
2460 =item -internal
2463 EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE.
2465 =item -function NAME
2472 =item -nosymbol NAME
2484 =item -no-doc-sections
2488 =item -export-file FILE
2492 To be used with -export or -internal.
2502 =item -enable-lineno
2512 =item -h, -help
2516 =item -v
2520 =item -Werror