Lines Matching +full:sub +full:- +full:function
2 # SPDX-License-Identifier: GPL-2.0
10 ## Copyright (C) 2005-2012 Randy Dunlap ##
19 # 18/01/2001 - Cleanups
22 # -- huggie@earth.li
24 # 27/06/2001 - Allowed whitespace after initial "/**" and
25 # allowed comments before function declarations.
26 # -- Christian Kreibich <ck@whoop.org>
29 # - add perldoc documentation
30 # - Look more closely at some of the scarier bits :)
32 # 26/05/2001 - Support for separate source and object trees.
36 # 23/09/2001 - Added support for typedefs, structs, enums and unions
39 # -- Tim Jansen <tim@tjansen.de>
41 # 25/07/2012 - Added support for HTML5
42 # -- Dan Luedtke <mail@danrl.de>
44 sub usage {
52 Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
55 -man Output troff manual page format. This is the default.
56 -rst Output reStructuredText format.
57 -none Do not output documentation, only warnings.
61 -sphinx-version Use the ReST C domain dialect compatible with an
63 If not specified, kernel-doc will auto-detect using
64 the sphinx-build version found on PATH.
67 -export Only output documentation for symbols that have been
69 in any input FILE or -export-file FILE.
70 -internal Only output documentation for symbols that have NOT been
72 in any input FILE or -export-file FILE.
73 -function NAME Only output documentation for the given function(s)
76 -nosymbol NAME Exclude the specified symbols from the output
80 -no-doc-sections Do not output DOC: sections.
81 -enable-lineno Enable output of #define LINENO lines. Only works with
83 -export-file FILE Specify an additional FILE in which to look for
85 -export or -internal. May be specified multiple times.
88 -v Verbose output, more warnings and other information.
89 -h Print this help.
90 -Werror Treat warnings as errors.
102 # * function_name(:)? (- short description)?
105 # * (Description:)? (Description of function)?
119 # * my_function - does my stuff
127 # * my_function - does my stuff
134 # enums and typedefs. Instead of the function name you must write the name
140 # * struct my_struct - short description
153 # All descriptions can be multiline, except the short function description.
159 # * struct my_struct - short description
180 # should document the "Context:" of the function, e.g. whether the functions
183 # A non-void function should have a "Return:" section describing the return
185 # Example-sections should contain the string EXAMPLE so that they are marked
190 # * user_function - function that can only be called in user context
204 # 'funcname()' - function
205 # '$ENVVAR' - environmental variable
206 # '&struct_name' - name of a structure (up to two words including 'struct')
207 # '&struct_name.member' - name of a structure member
208 # '@parameter' - name of a parameter
209 # '%CONST' - name of a constant.
210 # '``LITERAL``' - literal string without any spaces on it.
220 my $type_constant2 = '\%([-_\w]+)';
222 my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
223 my $type_param_ref = '([\!]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
225 my $type_fp_param2 = '\@(\w+->\S+)\(\)'; # Special RST handling for structs with func ptr params
231 my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
254 # rst-mode
275 if ($#ARGV == -1) {
298 OUTPUT_INTERNAL => 3, # output non-exported symbols
307 (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
322 my ($function, %function_table, %parametertypes, $declaration_purpose);
345 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
346 # https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
357 STATE_NAME => 1, # looking for function name
358 STATE_BODY_MAYBE => 2, # body - or maybe more description
375 STATE_INLINE_ERROR => 4, # error - Comment without header was found.
377 # proper kernel-doc and ignore the rest.
382 # 'function', 'struct', 'union', 'enum', 'typedef'
385 # Name of the kernel-doc identifier for non-DOC markups
397 # @{section-name}:
410 my $attribute = qr{__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)}i;
431 my $undescribed = "-- undescribed --";
435 while ($ARGV[0] =~ m/^--?(.*)/) {
450 } elsif ($cmd eq "function") { # to only output specific functions
452 $function = shift @ARGV;
453 $function_table{$function} = 1;
460 } elsif ($cmd eq "internal") { # only non-exported symbols
463 } elsif ($cmd eq "export-file") {
472 } elsif ($cmd eq 'no-doc-sections') {
474 } elsif ($cmd eq 'enable-lineno') {
476 } elsif ($cmd eq 'show-not-found') {
477 $show_not_found = 1; # A no-op but don't fail
478 } elsif ($cmd eq "sphinx-version") {
505 sub findprog($)
508 return "$_/$_[0]" if(-x "$_/$_[0]");
512 sub get_sphinx_version()
516 my $cmd = "sphinx-build";
518 my $cmd = "sphinx-build3";
529 open IN, "$cmd --version 2>&1 |";
531 if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {
549 sub get_kernel_version() {
559 sub print_lineno {
568 sub dump_section {
605 sub dump_doc_section {
624 'content-only' => ($output_selection != OUTPUT_ALL), });
629 # output function
632 # function => "function name"
639 sub output_highlight {
674 # output function in man
675 sub output_function_man(%) {
680 …print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" …
683 print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
687 print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
689 print ".B \"" . $args{'function'} . "\n";
700 # pointer-to-function
726 sub output_enum_man(%) {
734 print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
767 sub output_struct_man(%) {
774 print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
802 sub output_typedef_man(%) {
809 print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
817 sub output_blockhead_man(%) {
839 sub output_blockhead_rst(%) {
857 # Apply the RST highlights to a sub-block of text.
859 sub highlight_block($) {
871 my $sphinx_cblock = '^\.\.\ +code-block::';
873 sub output_highlight_rst {
889 # If this is the first non-blank line in a literal
927 sub output_function_rst(%) {
936 print ".. c:type:: ". $args{'function'} . "\n\n";
944 print ".. c:function:: ";
949 print ".. c:macro:: ". $args{'function'} . "\n\n";
951 print ".. c:function:: ";
965 $start .= $args{'functiontype'} . " " . $args{'function'} . " (";
967 $start .= $args{'function'} . " (";
980 # pointer-to-function
1026 sub output_section_rst(%) {
1042 sub output_enum_rst(%) {
1076 sub output_typedef_rst(%) {
1097 sub output_struct_rst(%) {
1147 sub output_function_none(%) {
1150 sub output_enum_none(%) {
1153 sub output_typedef_none(%) {
1156 sub output_struct_none(%) {
1159 sub output_blockhead_none(%) {
1163 # generic output function for all types (function, struct/union, typedef, enum);
1164 # calls the generated, variable output_ function name based on
1166 sub output_declaration {
1179 !($functype eq "function" && defined($function_table{$name}))))
1187 # generic output function - calls the right one based on current output mode.
1188 sub output_blockhead {
1198 sub dump_declaration($$) {
1205 sub dump_union($$) {
1209 sub dump_struct($$) {
1254 $members =~ s/DECLARE_HASHTABLE\s*\($args,\s*$args\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
1275 # pointer-to-function
1345 $level-- if ($clause =~ m/(\})/ && $level > 1);
1373 sub show_warnings($$) {
1389 if (!($functype eq "function" && defined($function_table{$name}))) {
1405 sub dump_enum($$) {
1426 print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
1481 sub dump_typedef($$) {
1487 # Parse function typedef prototypes
1502 'function',
1503 {'function' => $declaration_name,
1545 sub save_struct_actual($) {
1553 sub create_parameterlist($$$$) {
1561 # temporarily replace commas inside function pointer definition
1581 # pointer-to-function
1617 if ($type ne "") { # skip unnamed bit-fields
1631 sub push_parameter($$$$$) {
1683 …"${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n…
1702 sub check_sections($$$$$) {
1731 if ($decl_type eq "function") {
1733 "Excess function parameter " .
1743 # Checks the section describing the return value of a function.
1744 sub check_return_section {
1765 # takes a function prototype and the name of the current file being
1768 sub dump_function($$) {
1804 # 2. Function name
1805 # 3. Function parameters.
1807 # All the while we have to watch out for function pointer parameters
1814 # - parport_register_device (function pointer parameters)
1815 # - atomic_set (macro)
1816 # - pci_match_device, __copy_to_user (long return type)
1817 my $name = qr{[a-zA-Z0-9_~:]+};
1825 # This is an object-like macro, it has no return type and no parameter
1827 # Function-like macros are not allowed to have spaces between
1841 print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
1851 check_sections($file, $declaration_name, "function", $sectcheck, $prms);
1862 # The function parser can be called with a typedef parameter.
1866 'function',
1867 {'function' => $declaration_name,
1880 'function',
1881 {'function' => $declaration_name,
1894 sub reset_state {
1895 $function = "";
1909 sub tracepoint_munge($) {
1936 sub syscall_munge() {
1940 ## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
1953 # now delete all of the odd-number commas in $prototype
1958 $len = 0; # skip the for-loop
1970 sub process_proto_function($$) {
1974 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1988 # Handle prototypes for function pointers like:
2005 sub process_proto_type($$) {
2012 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2026 ($2 eq '}') && $brcount--;
2041 sub map_filename($) {
2058 sub process_export_file($) {
2083 sub process_normal() {
2085 $state = STATE_NAME; # next line is always the function name
2092 # STATE_NAME: Looking for the "name - description" line
2094 sub process_name($$) {
2112 # test for pointer declaration type, foo * bar() - desc
2115 my $decl_end = qr{[-:].*};
2124 # Look for foo() or static void foo() - description; or misspelt
2129 $decl_type = 'function';
2141 if (/[-:](.*)/) {
2154 … This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/ker…
2167 print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
2178 " - I thought it was a doc line\n";
2188 sub process_body($$) {
2254 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2299 # i dont know - bad line? ignore.
2307 # STATE_PROTO: reading a function/whatever prototype.
2309 sub process_proto($$) {
2324 } elsif ($decl_type eq 'function') {
2334 sub process_docblock($$) {
2341 $function = "";
2361 sub process_inline($$) {
2396 print STDERR "Incorrect use of kernel-doc format: $_";
2403 sub process_file($) {
2424 while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};