kernel-doc - OpenGrok cross reference for /openbmc/u-boot/scripts/kernel-doc

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
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
38 #              Small fixes (like spaces vs. \s in regex)
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.
60   -export		Only output documentation for symbols that have been
62                         in any input FILE or -export-file FILE.
63   -internal		Only output documentation for symbols that have NOT been
65                         in any input FILE or -export-file FILE.
66   -function NAME	Only output documentation for the given function(s)
69   -nofunction NAME	Do NOT output documentation for the given function(s);
74   -no-doc-sections	Do not output DOC: sections.
75   -enable-lineno        Enable output of #define LINENO lines. Only works with
77   -export-file FILE     Specify an additional FILE in which to look for
79                         -export or -internal. May be specified multiple times.
82   -v			Verbose output, more warnings and other information.
83   -h			Print this help.
95 #  * function_name(:)? (- short description)?
112 #  * my_function - does my stuff
120 #  * my_function - does my stuff
133 #  * struct my_struct - short description
152 #  * struct my_struct - short description
176 # A non-void function should have a "Return:" section describing the return
178 # Example-sections should contain the string EXAMPLE so that they are marked
183 #  * user_function - function that can only be called in user context
197 # 'funcname()' - function
198 # '$ENVVAR' - environmental variable
199 # '&struct_name' - name of a structure (up to two words including 'struct')
200 # '&struct_name.member' - name of a structure member
201 # '@parameter' - name of a parameter
202 # '%CONST' - name of a constant.
203 # '``LITERAL``' - literal string without any spaces on it.
213 my $type_constant2 = '\%([-_\w]+)';
222 my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
244 # rst-mode
264 if ($#ARGV == -1) {
285     OUTPUT_INTERNAL     => 4, # output non-exported symbols
294     (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
319 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
320 # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
332     STATE_BODY_MAYBE    => 2, # body - or maybe more description
348     STATE_INLINE_ERROR  => 4, # error - Comment without header was found.
350                               # proper kernel-doc and ignore the rest.
393 my $undescribed = "-- undescribed --";
397 while ($ARGV[0] =~ m/^--?(.*)/) {
423     } elsif ($cmd eq "internal") { # only non-exported symbols
426     } elsif ($cmd eq "export-file") {
433     } elsif ($cmd eq 'no-doc-sections') {
435     } elsif ($cmd eq 'enable-lineno') {
437     } elsif ($cmd eq 'show-not-found') {
448 sub get_kernel_version() {
458 sub print_lineno {
467 sub dump_section {
504 sub dump_doc_section {
523 			  'content-only' => ($output_selection != OUTPUT_ALL), });
538 sub output_highlight {
574 sub output_function_man(%) {
582     print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
599 	    # pointer-to-function
625 sub output_enum_man(%) {
633     print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
666 sub output_struct_man(%) {
673     print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
701 sub output_typedef_man(%) {
708     print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
716 sub output_blockhead_man(%) {
738 sub output_blockhead_rst(%) {
753 # Apply the RST highlights to a sub-block of text.
755 sub highlight_block($) {
767 my $sphinx_cblock = '^\.\.\ +code-block::';
769 sub output_highlight_rst {
785 		# If this is the first non-blank line in a literal
823 sub output_function_rst(%) {
855 	    # pointer-to-function
899 sub output_section_rst(%) {
915 sub output_enum_rst(%) {
944 sub output_typedef_rst(%) {
960 sub output_struct_rst(%) {
1001 sub output_function_none(%) {
1004 sub output_enum_none(%) {
1007 sub output_typedef_none(%) {
1010 sub output_struct_none(%) {
1013 sub output_blockhead_none(%) {
1020 sub output_declaration {
1039 # generic output function - calls the right one based on current output mode.
1040 sub output_blockhead {
1050 sub dump_declaration($$) {
1057 sub dump_union($$) {
1061 sub dump_struct($$) {
1076 	$members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
1082 	$members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
1104 					# pointer-to-function
1127 					# So, we remove spaces when parsing the
1174 		$level-- if ($clause =~ m/(})/ && $level > 1);
1202 sub show_warnings($$) {
1239 sub dump_enum($$) {
1291 sub dump_typedef($$) {
1347 sub save_struct_actual($) {
1350     # strip all spaces from the actual param so that it looks like one string item
1355 sub create_parameterlist($$$$) {
1371 	# strip leading/trailing spaces
1382 	    # pointer-to-function
1417 		    if ($type ne "") { # skip unnamed bit-fields
1431 sub push_parameter($$$$) {
1483 	# strip spaces from $param so that it is one continuous string
1497 sub check_sections($$$$$) {
1510 			$prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
1513 			# spaces, e.g.:  addr[6 + 2]
1515 			# parameter list is split at spaces;
1539 sub check_return_section {
1563 sub dump_function($$) {
1603     # - parport_register_device (function pointer parameters)
1604     # - atomic_set (macro)
1605     # - pci_match_device, __copy_to_user (long return type)
1607     if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
1608         # This is an object-like macro, it has no return type and no parameter
1610         # Function-like macros are not allowed to have spaces between
1615     } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1616 	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1617 	$prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1618 	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1619 	$prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1620 	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1621 	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1622 	$prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1623 	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1624 	$prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1625 	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1626 	$prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1627 	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1628 	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1629 	$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1630 	$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1631 	$prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
1668 sub reset_state {
1683 sub tracepoint_munge($) {
1709 sub syscall_munge() {
1713 ##	if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
1726 	# now delete all of the odd-number commas in $prototype
1731 		$len = 0;	# skip the for-loop
1743 sub process_proto_function($$) {
1747     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1759 	$prototype =~ s@^\s+@@gos; # strip leading spaces
1773 sub process_proto_type($$) {
1778     $x =~ s@^\s+@@gos; # strip leading spaces
1779     $x =~ s@\s+$@@gos; # strip trailing spaces
1780     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1794 	    ($2 eq '}') && $brcount--;
1809 sub map_filename($) {
1826 sub process_export_file($) {
1850 sub process_normal() {
1859 # STATE_NAME: Looking for the "name - description" line
1861 sub process_name($$) {
1879 	if (/\s*([\w\s]+?)(\(\))?\s*-/) {
1889 	if (/-(.*)/) {
1890 	    # strip leading/trailing/multiple spaces
1924 	    " - I thought it was a doc line\n";
1934 sub process_body($$) {
1981 	if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
1990 	# miguel-style comment kludge, look for blank lines after
2022 	# i dont know - bad line?  ignore.
2032 sub process_proto($$) {
2057 sub process_docblock($$) {
2084 sub process_inline($$) {
2119 	    print STDERR "Incorrect use of kernel-doc format: $_";
2126 sub process_file($) {
2146 	# Replace tabs by spaces
2147         while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};