linux-6.8/scripts/kernel-doc

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-desc[ription]] [-Wcontents-before-secti…
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.
62 # match expressions used to find embedded type information
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
103                        [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
104                        [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
108                        [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
109                        [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
110                        [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
111                        [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
112                        # in rst this can refer to any type
113                        [$type_fallback, "\\:c\\:type\\:`\$1`"],
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 '') {
178 my ($type, $declaration_name, $return_type);
188 	if ($kcflags =~ /(\s|^)-Werror(\s|$)/) {
199 # other environment variables are converted to command-line
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
216     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") {
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,
389 sub findprog($)
392 		return "$_/$_[0]" if(-x "$_/$_[0]");
396 sub get_sphinx_version()
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]+)?$/) {
433 sub get_kernel_version() {
443 sub print_lineno {
450 sub emit_warning {
459 sub dump_section {
495 sub dump_doc_section {
514 			  'content-only' => ($output_selection != OUTPUT_ALL), });
529 sub output_highlight {
565 sub output_function_man(%) {
573     print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
588 	$type = $args{'parametertypes'}{$parameter};
589 	if ($type =~ m/$function_pointer/) {
590 	    # pointer-to-function
593 	    $type =~ s/([^\*])$/$1 /;
594 	    print ".BI \"" . $parenth . $type . "\" " . " \"" . $post . "\"\n";
616 sub output_enum_man(%) {
624     print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
657 sub output_struct_man(%) {
661 …print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \…
664     print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
670     print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
692 sub output_typedef_man(%) {
699     print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
707 sub output_blockhead_man(%) {
729 sub output_blockhead_rst(%) {
747 # Apply the RST highlights to a sub-block of text.
749 sub highlight_block($) {
761 my $sphinx_cblock = '^\.\.\ +code-block::';
763 sub output_highlight_rst {
779 		# If this is the first non-blank line in a literal
817 sub output_function_rst(%) {
826 	    print ".. c:type:: ". $args{'function'} . "\n\n";
867 	$type = $args{'parametertypes'}{$parameter};
869 	if ($type =~ m/$function_pointer/) {
870 	    # pointer-to-function
873 	    print $type;
898 	$type = $args{'parametertypes'}{$parameter};
900 	if ($type ne "") {
901 	    print $lineprefix . "``$type``\n";
923 sub output_section_rst(%) {
937 sub output_enum_rst(%) {
946 	print "\n\n.. c:type:: " . $name . "\n\n";
975 sub output_typedef_rst(%) {
986     print "\n\n.. c:type:: " . $name . "\n\n";
996 sub output_struct_rst(%) {
1002 	my $name = $args{'type'} . " " . $args{'struct'};
1003 	print "\n\n.. c:type:: " . $name . "\n\n";
1006 	if ($args{'type'} eq 'union') {
1022 …print $lineprefix . $args{'type'} . " " . $args{'struct'} . " {\n$declaration" . $lineprefix . "};…
1033 	$type = $args{'parametertypes'}{$parameter};
1049 sub output_function_none(%) {
1052 sub output_enum_none(%) {
1055 sub output_typedef_none(%) {
1058 sub output_struct_none(%) {
1061 sub output_blockhead_none(%) {
1068 sub output_declaration {
1089 # generic output function - calls the right one based on current output mode.
1090 sub output_blockhead {
1100 sub dump_declaration($$) {
1107 sub dump_union($$) {
1111 sub dump_struct($$) {
1116     my $type = qr{struct|union};
1120     my $struct_members = qr{($type)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;};
1122     if ($x =~ /($type)\s+(\w+)\s*$definition_body/) {
1126     } elsif ($x =~ /typedef\s+($type)\s*$definition_body\s*(\w+)\s*;/) {
1152 	# - first eat non-declaration parameters and rewrite for final match
1153 	# - then remove macro, outer parens, and trailing semicolon
1165 	$members =~ s/DECLARE_HASHTABLE\s*\($args,\s*$args\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
1192 					# pointer-to-function
1193 					my $type = $1;
1199 						$newmember .= "$type$name$extra; ";
1201 						$newmember .= "$type$id.$name$extra; ";
1204 					my $type;
1212 					# The type may have multiple words,
1220 						$type = $1;
1231 							$newmember .= "$type $name; ";
1233 							$newmember .= "$type $id.$name; ";
1262 		$level-- if ($clause =~ m/(\})/ && $level > 1);
1280 			    'type' => $decl_type
1290 sub show_warnings($$) {
1319 	die("Please add the new output type at show_warnings()");
1322 sub dump_enum($$) {
1346 		emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n");
1402 sub dump_typedef($$) {
1466 sub save_struct_actual($) {
1474 sub create_parameterlist($$$$) {
1479     my $type;
1504 	    # pointer-to-function
1508 	    $type = $arg;
1509 	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
1511 	    push_parameter($param, $type, $arg, $file, $declaration_name);
1531 	    $type = join " ", @first_arg;
1537 		    push_parameter($2, "$type $1", $arg, $file, $declaration_name);
1540 		    if ($type ne "") { # skip unnamed bit-fields
1542 			push_parameter($1, "$type:$2", $arg, $file, $declaration_name)
1547 		    push_parameter($param, $type, $arg, $file, $declaration_name);
1554 sub push_parameter($$$$$) {
1556 	my $type = shift;
1561 	if (($anon_struct_union == 1) && ($type eq "") &&
1569 	if ($type eq "" && $param =~ /\.\.\.$/)
1583 	elsif ($type eq "" && ($param eq "" or $param eq "void"))
1588 	elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
1591 		$type = $param;
1609 	        if (show_warnings($type, $declaration_name) && $param !~ /\./) {
1628 sub check_sections($$$$$) {
1676 sub check_return_section {
1681         # Ignore an empty return type (It's a macro)
1682         # Ignore functions with a "void" return type. (But don't ignore "void *")
1699 sub dump_function($$) {
1737     # 1. Return type (may be nothing if we're looking at a macro)
1748     # - parport_register_device (function pointer parameters)
1749     # - atomic_set (macro)
1750     # - pci_match_device, __copy_to_user (long return type)
1751     my $name = qr{[a-zA-Z0-9_~:]+};
1759         # This is an object-like macro, it has no return type and no parameter
1761         # Function-like macros are not allowed to have spaces between
1790     # -Wreturn mode.
1828 sub reset_state {
1843 sub tracepoint_munge($) {
1870 sub syscall_munge() {
1874 ##	if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
1880 	$prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
1887 	# now delete all of the odd-number commas in $prototype
1892 		$len = 0;	# skip the for-loop
1904 sub process_proto_function($$) {
1908     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1939 sub process_proto_type($$) {
1946     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1960 	    ($2 eq '}') && $brcount--;
1975 sub map_filename($) {
1992 sub process_export_file($) {
2021 sub process_normal() {
2030 # STATE_NAME: Looking for the "name - description" line
2032 sub process_name($$) {
2050 	# test for pointer declaration type, foo * bar() - desc
2053 	my $decl_end = qr{[-:].*};
2062 	# Look for foo() or static void foo() - description; or misspelt
2079 	if (/[-:](.*)/) {
2092 …"This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/ker…
2101 	    emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n$_");
2109 	emit_warning("${file}:$.", "Cannot understand $_ on line $. - I thought it was a doc line\n");
2118 sub process_body($$) {
2172 	if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2216 	# i dont know - bad line?  ignore.
2225 sub process_proto($$) {
2250 sub process_docblock($$) {
2277 sub process_inline($$) {
2311 	    emit_warning("${file}:$.", "Incorrect use of kernel-doc format: $_");
2317 sub process_file($) {
2338         while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
2436 =item -man
2440 =item -rst
2444 =item -none
2456 =item -sphinx-version VERSION
2460 If not specified, kernel-doc will auto-detect using the sphinx-build version
2469 =item -export
2472 EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE.
2474 =item -internal
2477 EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE.
2479 =item -function NAME
2486 =item -nosymbol NAME
2498 =item -no-doc-sections
2502 =item -export-file FILE
2506 To be used with -export or -internal.
2516 =item -enable-lineno
2526 =item -h, -help
2530 =item -v
2534 =item -Werror