linux-6.15/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 [-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.
63 # match expressions used to find embedded type information
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
105     [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
106     [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
110     [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
111     [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
112     [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
113     [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
115     # in rst this can refer to any type
116     [$type_fallback, "\\:c\\:type\\:`\$1`"],
122 if ($#ARGV == -1) {
124         -message => "No arguments!\n",
125         -exitval => 1,
126         -verbose => 99,
127         -sections => 'SYNOPSIS',
128         -output => \*STDERR,
152     OUTPUT_INTERNAL     => 3, # output non-exported symbols
161     (my $seconds = `date -d "${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
179 my ($type, $declaration_name, $return_type);
189     if ($kcflags =~ /(\s|^)-Werror(\s|$)/) {
200 # other environment variables are converted to command-line
204 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
205 # https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
217     STATE_BODY_MAYBE    => 2,        # body - or maybe more description
233     STATE_INLINE_ERROR  => 4, # error - Comment without header was found.
235                               # proper kernel-doc and ignore the rest.
243 # Name of the kernel-doc identifier for non-DOC markups
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" or $cmd eq "Wshort-description") {
337         pod2usage(-exitval => 0, -verbose => 2);
338     } elsif ($cmd eq 'no-doc-sections') {
340     } elsif ($cmd eq 'enable-lineno') {
342     } elsif ($cmd eq 'show-not-found') {
343         $show_not_found = 1;  # A no-op but don't fail
347             -message => "Argument unknown!\n",
348             -exitval => 1,
349             -verbose => 99,
350             -sections => 'SYNOPSIS',
351             -output => \*STDERR,
356             -message => "FILE argument missing\n",
357             -exitval => 1,
358             -verbose => 99,
359             -sections => 'SYNOPSIS',
360             -output => \*STDERR,
367 sub findprog($)
370         return "$_/$_[0]" if(-x "$_/$_[0]");
375 sub get_kernel_version() {
385 sub print_lineno {
392 sub emit_warning {
401 sub dump_section {
437 sub dump_doc_section {
456                           'content-only' => ($output_selection != OUTPUT_ALL), });
471 sub output_highlight {
507 sub output_function_man(%) {
512     my $paramcount = $#{$args{'parameterlist'}}; # -1 is empty
517     print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
532         $type = $args{'parametertypes'}{$parameter};
533         if ($type =~ m/$function_pointer/) {
534             # pointer-to-function
537             $type =~ s/([^\*])$/$1 /;
538             print ".BI \"" . $parenth . $type . "\" " . " \"" . $post . "\"\n";
544     $paramcount = $#{$args{'parameterlist'}}; # -1 is empty
563 sub output_enum_man(%) {
571     print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
603 sub output_struct_man(%) {
607 …print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \…
610     print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
616     print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
638 sub output_typedef_man(%) {
645     print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
653 sub output_blockhead_man(%) {
675 sub output_blockhead_rst(%) {
693 # Apply the RST highlights to a sub-block of text.
695 sub highlight_block($) {
707 my $sphinx_cblock = '^\.\.\ +code-block::';
709 sub output_highlight_rst {
725                 # If this is the first non-blank line in a literal
767 sub output_function_rst(%) {
774     my $paramcount = $#{$args{'parameterlist'}}; # -1 is empty
791         $type = $args{'parametertypes'}{$parameter};
793         if ($type =~ m/$function_pointer/) {
794             # pointer-to-function
797             $signature .= $type;
841         $type = $args{'parametertypes'}{$parameter};
843         if ($type ne "") {
844             print $lineprefix . "``$type``\n";
866 sub output_section_rst(%) {
880 sub output_enum_rst(%) {
914 sub output_typedef_rst(%) {
922     print "\n\n.. c:type:: " . $name . "\n\n";
932 sub output_struct_rst(%) {
938     if ($args{'type'} eq 'union') {
954 …print $lineprefix . $args{'type'} . " " . $args{'struct'} . " {\n$declaration" . $lineprefix . "};…
965         $type = $args{'parametertypes'}{$parameter};
981 sub output_function_none(%) {
984 sub output_enum_none(%) {
987 sub output_typedef_none(%) {
990 sub output_struct_none(%) {
993 sub output_blockhead_none(%) {
1000 sub output_declaration {
1021 # generic output function - calls the right one based on current output mode.
1022 sub output_blockhead {
1032 sub dump_declaration($$) {
1039 sub dump_union($$) {
1043 sub dump_struct($$) {
1048     my $type = qr{struct|union};
1052     my $struct_members = qr{($type)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;};
1054     if ($x =~ /($type)\s+(\w+)\s*$definition_body/) {
1058     } elsif ($x =~ /typedef\s+($type)\s*$definition_body\s*(\w+)\s*;/) {
1085         # - first eat non-declaration parameters and rewrite for final match
1086         # - then remove macro, outer parens, and trailing semicolon
1099 …      $members =~ s/DECLARE_HASHTABLE\s*\($args,\s*$args\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
1126                         # pointer-to-function
1127                         my $type = $1;
1133                             $newmember .= "$type$name$extra; ";
1135                             $newmember .= "$type$id.$name$extra; ";
1138                         my $type;
1146                         # The type may have multiple words,
1154                             $type = $1;
1165                                 $newmember .= "$type $name; ";
1167                                 $newmember .= "$type $id.$name; ";
1196             $level-- if ($clause =~ m/(\})/ && $level > 1);
1214                     'type' => $decl_type
1223 sub show_warnings($$) {
1252     die("Please add the new output type at show_warnings()");
1255 sub dump_enum($$) {
1279                 emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n");
1335 sub dump_typedef($$) {
1398 sub save_struct_actual($) {
1406 sub create_parameterlist($$$$) {
1411     my $type;
1436             # pointer-to-function
1440             $type = $arg;
1441             $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
1443             push_parameter($param, $type, $arg, $file, $declaration_name);
1445             # array-of-pointers
1449             $type = $arg;
1450             $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
1452             push_parameter($param, $type, $arg, $file, $declaration_name);
1472             $type = join " ", @first_arg;
1478                     push_parameter($2, "$type $1", $arg, $file, $declaration_name);
1480                     if ($type ne "") { # skip unnamed bit-fields
1482                         push_parameter($1, "$type:$2", $arg, $file, $declaration_name)
1486                     push_parameter($param, $type, $arg, $file, $declaration_name);
1493 sub push_parameter($$$$$) {
1495     my $type = shift;
1500     if (($anon_struct_union == 1) && ($type eq "") &&
1508     if ($type eq "" && $param =~ /\.\.\.$/)
1521     elsif ($type eq "" && ($param eq "" or $param eq "void"))
1526     elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
1529         $type = $param;
1547         if (show_warnings($type, $declaration_name) && $param !~ /\./) {
1566 sub check_sections($$$$$) {
1613 sub check_return_section {
1618     # Ignore an empty return type (It's a macro)
1619     # Ignore functions with a "void" return type. (But don't ignore "void *")
1637 sub dump_function($$) {
1677     # 1. Return type (may be nothing if we're looking at a macro)
1688     # - parport_register_device (function pointer parameters)
1689     # - atomic_set (macro)
1690     # - pci_match_device, __copy_to_user (long return type)
1691     my $name = qr{[a-zA-Z0-9_~:]+};
1699         # This is an object-like macro, it has no return type and no parameter
1701         # Function-like macros are not allowed to have spaces between
1730     # -Wreturn mode.
1770 sub reset_state {
1785 sub tracepoint_munge($) {
1812 sub syscall_munge() {
1816 ##    if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
1822     $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
1829     # now delete all of the odd-number commas in $prototype
1834         $len = 0;    # skip the for-loop
1846 sub process_proto_function($$) {
1850     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1880 sub process_proto_type($$) {
1887     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1901             ($2 eq '}') && $brcount--;
1916 sub map_filename($) {
1929 sub process_export_file($) {
1958 sub process_normal() {
1966 # STATE_NAME: Looking for the "name - description" line
1968 sub process_name($$) {
1986         # test for pointer declaration type, foo * bar() - desc
1989         my $decl_end = qr{[-:].*};
1998         # Look for foo() or static void foo() - description; or misspelt
2001             /^$decl_start$fn_type?(\w+[^-:]*)$parenthesis?\s*$decl_end$/) {
2015         if (/[-:](.*)/) {
2028 …"This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/ker…
2037             emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n$_");
2045 …     emit_warning("${file}:$.", "Cannot understand $_ on line $. - I thought it was a doc line\n");
2054 sub process_body($$) {
2103         if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2147         # i dont know - bad line?  ignore.
2156 sub process_proto($$) {
2181 sub process_docblock($$) {
2208 sub process_inline($$) {
2242             emit_warning("${file}:$.", "Incorrect use of kernel-doc format: $_");
2248 sub process_file($) {
2268         while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
2346 =item -man
2350 =item -rst
2354 =item -none
2368 =item -export
2371 EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE.
2373 =item -internal
2376 EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE.
2378 =item -function NAME
2385 =item -nosymbol NAME
2397 =item -no-doc-sections
2401 =item -export-file FILE
2405 To be used with -export or -internal.
2415 =item -enable-lineno
2425 =item -h, -help
2429 =item -v
2433 =item -Werror