Lines Matching +full:sub +full:- +full:function
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 '') {
178 my ($function, %function_table, %parametertypes, $declaration_purpose);
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
218 STATE_NAME => 1, # looking for function name
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.
243 # 'function', 'struct', 'union', 'enum', 'typedef'
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/^--?(.*)/) {
312 } elsif ($cmd eq "function") { # to only output specific functions
314 $function = shift @ARGV;
315 $function_table{$function} = 1;
322 } elsif ($cmd eq "internal") { # only non-exported symbols
325 } elsif ($cmd eq "export-file") {
334 } elsif ($cmd eq "Wshort-desc" or $cmd eq "Wshort-description") {
336 } elsif ($cmd eq "Wcontents-before-sections") {
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,
392 sub findprog($)
395 return "$_/$_[0]" if(-x "$_/$_[0]");
399 sub get_sphinx_version()
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]+)?$/) {
436 sub get_kernel_version() {
446 sub print_lineno {
453 sub emit_warning {
462 sub dump_section {
498 sub dump_doc_section {
517 'content-only' => ($output_selection != OUTPUT_ALL), });
522 # output function
525 # function => "function name"
532 sub output_highlight {
567 # output function in man
568 sub output_function_man(%) {
573 …print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" …
576 print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
580 print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
582 print ".B \"" . $args{'function'} . "\n";
593 # pointer-to-function
619 sub output_enum_man(%) {
627 print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
659 sub output_struct_man(%) {
666 print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
694 sub output_typedef_man(%) {
701 print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
709 sub output_blockhead_man(%) {
731 sub output_blockhead_rst(%) {
749 # Apply the RST highlights to a sub-block of text.
751 sub highlight_block($) {
763 my $sphinx_cblock = '^\.\.\ +code-block::';
765 sub output_highlight_rst {
781 # If this is the first non-blank line in a literal
819 sub output_function_rst(%) {
826 $signature = $args{'functiontype'} . " " . $args{'function'} . " (";
828 $signature = $args{'function'} . " (";
840 # pointer-to-function
851 print ".. c:type:: ". $args{'function'} . "\n\n";
859 print ".. c:function:: $signature\n\n";
863 print ".. c:macro:: ". $args{'function'} . "\n\n";
876 print ".. c:function:: $signature\n\n";
889 # set the function prototypes apart.
922 sub output_section_rst(%) {
936 sub output_enum_rst(%) {
974 sub output_typedef_rst(%) {
995 sub output_struct_rst(%) {
1048 sub output_function_none(%) {
1051 sub output_enum_none(%) {
1054 sub output_typedef_none(%) {
1057 sub output_struct_none(%) {
1060 sub output_blockhead_none(%) {
1064 # generic output function for all types (function, struct/union, typedef, enum);
1065 # calls the generated, variable output_ function name based on
1067 sub output_declaration {
1080 !($functype eq "function" && defined($function_table{$name}))))
1088 # generic output function - calls the right one based on current output mode.
1089 sub output_blockhead {
1099 sub dump_declaration($$) {
1106 sub dump_union($$) {
1110 sub dump_struct($$) {
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
1263 $level-- if ($clause =~ m/(\})/ && $level > 1);
1290 sub show_warnings($$) {
1306 if (!($functype eq "function" && defined($function_table{$name}))) {
1322 sub dump_enum($$) {
1346 emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n");
1402 sub dump_typedef($$) {
1408 # Parse function typedef prototypes
1423 'function',
1424 {'function' => $declaration_name,
1465 sub save_struct_actual($) {
1473 sub create_parameterlist($$$$) {
1481 # temporarily replace commas inside function pointer definition
1503 # pointer-to-function
1512 # array-of-pointers
1547 if ($type ne "") { # skip unnamed bit-fields
1560 sub push_parameter($$$$$) {
1615 …emit_warning("${file}:$.", "Function parameter or struct member '$param' not described in '$declar…
1633 sub check_sections($$$$$) {
1662 if ($decl_type eq "function") {
1664 "Excess function parameter " .
1679 # Checks the section describing the return value of a function.
1680 sub check_return_section {
1701 # takes a function prototype and the name of the current file being
1704 sub dump_function($$) {
1745 # 2. Function name
1746 # 3. Function parameters.
1748 # All the while we have to watch out for function pointer parameters
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
1782 emit_warning("${file}:$.", "cannot understand function prototype: '$prototype'\n");
1792 check_sections($file, $declaration_name, "function", $sectcheck, $prms);
1797 # -Wreturn mode.
1803 # The function parser can be called with a typedef parameter.
1807 'function',
1808 {'function' => $declaration_name,
1821 'function',
1822 {'function' => $declaration_name,
1835 sub reset_state {
1836 $function = "";
1850 sub tracepoint_munge($) {
1877 sub syscall_munge() {
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
1911 sub process_proto_function($$) {
1915 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1928 # Handle prototypes for function pointers like:
1945 sub process_proto_type($$) {
1952 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1966 ($2 eq '}') && $brcount--;
1981 sub map_filename($) {
1998 sub process_export_file($) {
2027 sub process_normal() {
2029 $state = STATE_NAME; # next line is always the function name
2036 # STATE_NAME: Looking for the "name - description" line
2038 sub process_name($$) {
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
2073 $decl_type = 'function';
2085 if (/[-:](.*)/) {
2098 …"This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/ker…
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");
2124 sub process_body($$) {
2178 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2222 # i dont know - bad line? ignore.
2229 # STATE_PROTO: reading a function/whatever prototype.
2231 sub process_proto($$) {
2246 } elsif ($decl_type eq 'function') {
2256 sub process_docblock($$) {
2263 $function = "";
2283 sub process_inline($$) {
2317 emit_warning("${file}:$.", "Incorrect use of kernel-doc format: $_");
2323 sub process_file($) {
2344 while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
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
2486 Only output documentation for the given function or DOC: section title.
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