linux-6.12.1/scripts/kernel-doc

2 # SPDX-License-Identifier: GPL-2.0
11 ## Copyright (C) 2005-2012  Randy Dunlap                         ##
23 kernel-doc - Print formatted kernel documentation to stdout
27 …kernel-doc [-h] [-v] [-Werror] [-Wall] [-Wreturn] [-Wshort-desc[ription]] [-Wcontents-before-secti…
28    [ -man |
29      -rst [-sphinx-version VERSION] [-enable-lineno] |
30      -none
33      -export |
34      -internal |
35      [-function NAME] ... |
36      [-nosymbol NAME] ...
38    [-no-doc-sections]
39    [-export-file FILE] ...
42 Run `kernel-doc -h` for details.
51 See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
65 my $type_constant2 = '\%([-_*\w]+)';
67 my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
68 my $type_param_ref = '([\!~\*]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
70 my $type_fp_param2 = '\@(\w+->\S+)\(\)';  # Special RST handling for structs with func ptr params
76 my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
99 # rst-mode
122 if ($#ARGV == -1) {
124         -message => "No arguments!\n",
125         -exitval => 1,
126         -verbose => 99,
127         -sections => 'SYNOPSIS',
128         -output => \*STDERR,
154     OUTPUT_INTERNAL     => 3, # output non-exported symbols
163     (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
191     if ($kcflags =~ /(\s|^)-Werror(\s|$)/) {
202 # other environment variables are converted to command-line
206 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
207 # https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
219     STATE_BODY_MAYBE    => 2,        # body - or maybe more description
236     STATE_INLINE_ERROR  => 4, # error - Comment without header was found.
238                               # proper kernel-doc and ignore the rest.
246 # Name of the kernel-doc identifier for non-DOC markups
258 #         @{section-name}:
272 my $attribute = qr{__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)}i;
293 my $undescribed = "-- undescribed --";
297 while ($ARGV[0] =~ m/^--?(.*)/) {
300     if ($cmd eq "man") {
304     } elsif ($cmd eq "rst") {
308     } elsif ($cmd eq "none") {
310     } elsif ($cmd eq "module") { # not needed for XML, inherits from calling document
312     } elsif ($cmd eq "function") { # to only output specific functions
316     } elsif ($cmd eq "nosymbol") { # Exclude specific symbols
319     } elsif ($cmd eq "export") { # only exported symbols
322     } elsif ($cmd eq "internal") { # only non-exported symbols
325     } elsif ($cmd eq "export-file") {
328     } elsif ($cmd eq "v") {
330     } elsif ($cmd eq "Werror") {
332     } elsif ($cmd eq "Wreturn") {
334     } elsif ($cmd eq "Wshort-desc" or $cmd eq "Wshort-description") {
336     } elsif ($cmd eq "Wcontents-before-sections") {
338     } elsif ($cmd eq "Wall") {
342     } elsif (($cmd eq "h") || ($cmd eq "help")) {
343         pod2usage(-exitval => 0, -verbose => 2);
344     } elsif ($cmd eq 'no-doc-sections') {
346     } elsif ($cmd eq 'enable-lineno') {
348     } elsif ($cmd eq 'show-not-found') {
349         $show_not_found = 1;  # A no-op but don't fail
350     } elsif ($cmd eq "sphinx-version") {
370             -message => "Argument unknown!\n",
371             -exitval => 1,
372             -verbose => 99,
373             -sections => 'SYNOPSIS',
374             -output => \*STDERR,
379             -message => "FILE argument missing\n",
380             -exitval => 1,
381             -verbose => 99,
382             -sections => 'SYNOPSIS',
383             -output => \*STDERR,
395         return "$_/$_[0]" if(-x "$_/$_[0]");
403     my $cmd = "sphinx-build";
405         my $cmd = "sphinx-build3";
416     open IN, "$cmd --version 2>&1 |";
418         if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {
473     } elsif ($name eq "@\.\.\.") {
517                           'content-only' => ($output_selection != OUTPUT_ALL), });
551         if ($line eq ""){
556             if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
576     print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
593             # pointer-to-function
627     print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
666     print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
701     print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
749 # Apply the RST highlights to a sub-block of text.
763 my $sphinx_cblock = '^\.\.\ +code-block::';
781                 # If this is the first non-blank line in a literal
784                 if ($litprefix eq "") {
840             # pointer-to-function
862         if ($args{'typedef'} || $args{'functiontype'} eq "") {
1005         if ($args{'type'} eq 'union') {
1080          !($functype eq "function" && defined($function_table{$name}))))
1088 # generic output function - calls the right one based on current output mode.
1152         # - first eat non-declaration parameters and rewrite for final match
1153         # - then remove macro, outer parens, and trailing semicolon
1166 …      $members =~ s/DECLARE_HASHTABLE\s*\($args,\s*$args\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
1193                         # pointer-to-function
1256         my $level = 1;
1263             $level-- if ($clause =~ m/(\})/ && $level > 1);
1265                 $declaration .= "\t" x $level;
1268             $level++ if ($clause =~ m/(\{)/ && !($clause =~m/\}/));
1306         if (!($functype eq "function" && defined($function_table{$name}))) {
1345             if ($identifier eq "") {
1346                 emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n");
1352         $declaration_name = "(anonymous)" if ($declaration_name eq "");
1503             # pointer-to-function
1512             # array-of-pointers
1547                     if ($type ne "") { # skip unnamed bit-fields
1567     if (($anon_struct_union == 1) && ($type eq "") &&
1568         ($param eq "}")) {
1575     if ($type eq "" && $param =~ /\.\.\.$/)
1584         if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
1588     elsif ($type eq "" && ($param eq "" or $param eq "void"))
1593     elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
1656             if ($prm_clean eq $sects[$sx]) {
1662             if ($decl_type eq "function") {
1667             } elsif (($decl_type eq "struct") or
1668                           ($decl_type eq "union")) {
1687     if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
1692         $sections{$section_return} eq "")
1755     # - parport_register_device (function pointer parameters)
1756     # - atomic_set (macro)
1757     # - pci_match_device, __copy_to_user (long return type)
1758     my $name = qr{[a-zA-Z0-9_~:]+};
1766         # This is an object-like macro, it has no return type and no parameter
1768         # Function-like macros are not allowed to have spaces between
1797     # -Wreturn mode.
1868     if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
1881 ##    if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
1894     # now delete all of the odd-number commas in $prototype
1899         $len = 0;    # skip the for-loop
1902         if (substr($prototype, $ix, 1) eq ',') {
1915     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1952     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1965             ($2 eq '{') && $brcount++;
1966             ($2 eq '}') && $brcount--;
1967             if (($2 eq ';') && ($brcount == 0)) {
2036 # STATE_NAME: Looking for the "name - description" line
2047         if ( $1 eq "" ) {
2056         # test for pointer declaration type, foo * bar() - desc
2059         my $decl_end = qr{[-:].*};
2068         # Look for foo() or static void foo() - description; or misspelt
2085         if (/[-:](.*)/) {
2098 …"This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/ker…
2102         if (($declaration_purpose eq "") && $Wshort_desc) {
2106         if ($identifier eq "" && $decl_type ne "enum") {
2107             emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n$_");
2115 …     emit_warning("${file}:$.", "Cannot understand $_ on line $. - I thought it was a doc line\n");
2163         while (substr($contents, 0, 1) eq " ") {
2178         if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2187         if ($1 eq "") {
2188             if ($section eq $section_context) {
2209             if ($section =~ m/^@/ || $section eq $section_context) {
2222         # i dont know - bad line?  ignore.
2246     } elsif ($decl_type eq 'function') {
2272         if ( $1 eq "" )        {
2292             while (substr($contents, 0, 1) eq " ") {
2317             emit_warning("${file}:$.", "Incorrect use of kernel-doc format: $_");
2344         while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
2376 if ($output_mode eq "rst") {
2430     exit($output_mode eq "none" ? 0 : $errors)
2441 =item -man
2445 =item -rst
2449 =item -none
2461 =item -sphinx-version VERSION
2465 If not specified, kernel-doc will auto-detect using the sphinx-build version
2474 =item -export
2477 EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE.
2479 =item -internal
2482 EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE.
2484 =item -function NAME
2491 =item -nosymbol NAME
2503 =item -no-doc-sections
2507 =item -export-file FILE
2511 To be used with -export or -internal.
2521 =item -enable-lineno
2531 =item -h, -help
2535 =item -v
2539 =item -Werror