2017-05-07 15:25:26 -06:00
|
|
|
#!/usr/bin/env perl
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2017-05-07 15:25:26 -06:00
|
|
|
use warnings;
|
2005-04-16 16:20:36 -06:00
|
|
|
use strict;
|
|
|
|
|
|
|
|
## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
|
|
|
|
## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
|
|
|
|
## Copyright (C) 2001 Simon Huggins ##
|
2012-01-21 11:31:54 -07:00
|
|
|
## Copyright (C) 2005-2012 Randy Dunlap ##
|
2012-08-12 02:46:15 -06:00
|
|
|
## Copyright (C) 2012 Dan Luedtke ##
|
2005-04-16 16:20:36 -06:00
|
|
|
## ##
|
|
|
|
## #define enhancements by Armin Kuster <akuster@mvista.com> ##
|
|
|
|
## Copyright (c) 2000 MontaVista Software, Inc. ##
|
|
|
|
## ##
|
|
|
|
## This software falls under the GNU General Public License. ##
|
|
|
|
## Please read the COPYING file for more information ##
|
|
|
|
|
|
|
|
# 18/01/2001 - Cleanups
|
|
|
|
# Functions prototyped as foo(void) same as foo()
|
|
|
|
# Stop eval'ing where we don't need to.
|
|
|
|
# -- huggie@earth.li
|
|
|
|
|
|
|
|
# 27/06/2001 - Allowed whitespace after initial "/**" and
|
|
|
|
# allowed comments before function declarations.
|
|
|
|
# -- Christian Kreibich <ck@whoop.org>
|
|
|
|
|
|
|
|
# Still to do:
|
|
|
|
# - add perldoc documentation
|
|
|
|
# - Look more closely at some of the scarier bits :)
|
|
|
|
|
|
|
|
# 26/05/2001 - Support for separate source and object trees.
|
|
|
|
# Return error code.
|
|
|
|
# Keith Owens <kaos@ocs.com.au>
|
|
|
|
|
|
|
|
# 23/09/2001 - Added support for typedefs, structs, enums and unions
|
|
|
|
# Support for Context section; can be terminated using empty line
|
|
|
|
# Small fixes (like spaces vs. \s in regex)
|
|
|
|
# -- Tim Jansen <tim@tjansen.de>
|
|
|
|
|
2012-08-12 02:46:15 -06:00
|
|
|
# 25/07/2012 - Added support for HTML5
|
|
|
|
# -- Dan Luedtke <mail@danrl.de>
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2016-05-12 07:15:36 -06:00
|
|
|
sub usage {
|
|
|
|
my $message = <<"EOF";
|
|
|
|
Usage: $0 [OPTION ...] FILE ...
|
|
|
|
|
|
|
|
Read C language source or header FILEs, extract embedded documentation comments,
|
|
|
|
and print formatted documentation to standard output.
|
|
|
|
|
|
|
|
The documentation comments are identified by "/**" opening comment mark. See
|
2017-12-18 05:30:08 -07:00
|
|
|
Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
|
2016-05-12 07:15:36 -06:00
|
|
|
|
|
|
|
Output format selection (mutually exclusive):
|
|
|
|
-man Output troff manual page format. This is the default.
|
2016-05-12 07:15:37 -06:00
|
|
|
-rst Output reStructuredText format.
|
2017-11-20 11:40:40 -07:00
|
|
|
-none Do not output documentation, only warnings.
|
2016-05-12 07:15:36 -06:00
|
|
|
|
|
|
|
Output selection (mutually exclusive):
|
2016-01-21 04:05:22 -07:00
|
|
|
-export Only output documentation for symbols that have been
|
|
|
|
exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
|
2016-06-07 02:05:53 -06:00
|
|
|
in any input FILE or -export-file FILE.
|
2016-01-21 04:05:22 -07:00
|
|
|
-internal Only output documentation for symbols that have NOT been
|
|
|
|
exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
|
2016-06-07 02:05:53 -06:00
|
|
|
in any input FILE or -export-file FILE.
|
2016-05-12 07:15:36 -06:00
|
|
|
-function NAME Only output documentation for the given function(s)
|
|
|
|
or DOC: section title(s). All other functions and DOC:
|
|
|
|
sections are ignored. May be specified multiple times.
|
|
|
|
-nofunction NAME Do NOT output documentation for the given function(s);
|
|
|
|
only output documentation for the other functions and
|
|
|
|
DOC: sections. May be specified multiple times.
|
|
|
|
|
|
|
|
Output selection modifiers:
|
|
|
|
-no-doc-sections Do not output DOC: sections.
|
2016-06-03 14:21:34 -06:00
|
|
|
-enable-lineno Enable output of #define LINENO lines. Only works with
|
|
|
|
reStructuredText format.
|
2016-06-07 02:00:52 -06:00
|
|
|
-export-file FILE Specify an additional FILE in which to look for
|
|
|
|
EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
|
|
|
|
-export or -internal. May be specified multiple times.
|
2016-05-12 07:15:36 -06:00
|
|
|
|
|
|
|
Other parameters:
|
|
|
|
-v Verbose output, more warnings and other information.
|
|
|
|
-h Print this help.
|
|
|
|
|
|
|
|
EOF
|
|
|
|
print $message;
|
|
|
|
exit 1;
|
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
#
|
|
|
|
# format of comments.
|
|
|
|
# In the following table, (...)? signifies optional structure.
|
|
|
|
# (...)* signifies 0 or more structure elements
|
|
|
|
# /**
|
|
|
|
# * function_name(:)? (- short description)?
|
|
|
|
# (* @parameterx: (description of parameter x)?)*
|
|
|
|
# (* a blank line)?
|
|
|
|
# * (Description:)? (Description of function)?
|
|
|
|
# * (section header: (section description)? )*
|
|
|
|
# (*)?*/
|
|
|
|
#
|
|
|
|
# So .. the trivial example would be:
|
|
|
|
#
|
|
|
|
# /**
|
|
|
|
# * my_function
|
2009-06-09 09:50:38 -06:00
|
|
|
# */
|
2005-04-16 16:20:36 -06:00
|
|
|
#
|
2007-02-10 02:45:53 -07:00
|
|
|
# If the Description: header tag is omitted, then there must be a blank line
|
2005-04-16 16:20:36 -06:00
|
|
|
# after the last parameter specification.
|
|
|
|
# e.g.
|
|
|
|
# /**
|
|
|
|
# * my_function - does my stuff
|
|
|
|
# * @my_arg: its mine damnit
|
|
|
|
# *
|
2006-02-01 04:06:58 -07:00
|
|
|
# * Does my stuff explained.
|
2005-04-16 16:20:36 -06:00
|
|
|
# */
|
|
|
|
#
|
|
|
|
# or, could also use:
|
|
|
|
# /**
|
|
|
|
# * my_function - does my stuff
|
|
|
|
# * @my_arg: its mine damnit
|
2006-02-01 04:06:58 -07:00
|
|
|
# * Description: Does my stuff explained.
|
2005-04-16 16:20:36 -06:00
|
|
|
# */
|
|
|
|
# etc.
|
|
|
|
#
|
2009-06-09 09:50:38 -06:00
|
|
|
# Besides functions you can also write documentation for structs, unions,
|
2006-02-01 04:06:58 -07:00
|
|
|
# enums and typedefs. Instead of the function name you must write the name
|
|
|
|
# of the declaration; the struct/union/enum/typedef must always precede
|
|
|
|
# the name. Nesting of declarations is not supported.
|
2005-04-16 16:20:36 -06:00
|
|
|
# Use the argument mechanism to document members or constants.
|
|
|
|
# e.g.
|
|
|
|
# /**
|
|
|
|
# * struct my_struct - short description
|
|
|
|
# * @a: first member
|
|
|
|
# * @b: second member
|
2006-02-01 04:06:58 -07:00
|
|
|
# *
|
2005-04-16 16:20:36 -06:00
|
|
|
# * Longer description
|
|
|
|
# */
|
|
|
|
# struct my_struct {
|
|
|
|
# int a;
|
|
|
|
# int b;
|
2005-11-13 17:08:13 -07:00
|
|
|
# /* private: */
|
|
|
|
# int c;
|
2005-04-16 16:20:36 -06:00
|
|
|
# };
|
|
|
|
#
|
|
|
|
# All descriptions can be multiline, except the short function description.
|
2006-02-01 04:06:58 -07:00
|
|
|
#
|
2015-08-04 06:04:08 -06:00
|
|
|
# For really longs structs, you can also describe arguments inside the
|
|
|
|
# body of the struct.
|
|
|
|
# eg.
|
|
|
|
# /**
|
|
|
|
# * struct my_struct - short description
|
|
|
|
# * @a: first member
|
|
|
|
# * @b: second member
|
|
|
|
# *
|
|
|
|
# * Longer description
|
|
|
|
# */
|
|
|
|
# struct my_struct {
|
|
|
|
# int a;
|
|
|
|
# int b;
|
|
|
|
# /**
|
|
|
|
# * @c: This is longer description of C
|
|
|
|
# *
|
|
|
|
# * You can use paragraphs to describe arguments
|
|
|
|
# * using this method.
|
|
|
|
# */
|
|
|
|
# int c;
|
|
|
|
# };
|
|
|
|
#
|
|
|
|
# This should be use only for struct/enum members.
|
|
|
|
#
|
2006-02-01 04:06:58 -07:00
|
|
|
# You can also add additional sections. When documenting kernel functions you
|
|
|
|
# should document the "Context:" of the function, e.g. whether the functions
|
2005-04-16 16:20:36 -06:00
|
|
|
# can be called form interrupts. Unlike other sections you can end it with an
|
2006-02-01 04:06:58 -07:00
|
|
|
# empty line.
|
2012-11-26 14:22:27 -07:00
|
|
|
# A non-void function should have a "Return:" section describing the return
|
|
|
|
# value(s).
|
2006-02-01 04:06:58 -07:00
|
|
|
# Example-sections should contain the string EXAMPLE so that they are marked
|
2005-04-16 16:20:36 -06:00
|
|
|
# appropriately in DocBook.
|
|
|
|
#
|
|
|
|
# Example:
|
|
|
|
# /**
|
|
|
|
# * user_function - function that can only be called in user context
|
|
|
|
# * @a: some argument
|
|
|
|
# * Context: !in_interrupt()
|
2006-02-01 04:06:58 -07:00
|
|
|
# *
|
2005-04-16 16:20:36 -06:00
|
|
|
# * Some description
|
|
|
|
# * Example:
|
|
|
|
# * user_function(22);
|
|
|
|
# */
|
|
|
|
# ...
|
|
|
|
#
|
|
|
|
#
|
|
|
|
# All descriptive text is further processed, scanning for the following special
|
|
|
|
# patterns, which are highlighted appropriately.
|
|
|
|
#
|
|
|
|
# 'funcname()' - function
|
|
|
|
# '$ENVVAR' - environmental variable
|
|
|
|
# '&struct_name' - name of a structure (up to two words including 'struct')
|
2017-01-02 08:22:26 -07:00
|
|
|
# '&struct_name.member' - name of a structure member
|
2005-04-16 16:20:36 -06:00
|
|
|
# '@parameter' - name of a parameter
|
|
|
|
# '%CONST' - name of a constant.
|
2017-03-30 14:11:28 -06:00
|
|
|
# '``LITERAL``' - literal string without any spaces on it.
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2011-01-05 17:28:43 -07:00
|
|
|
## init lots of data
|
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
my $errors = 0;
|
|
|
|
my $warnings = 0;
|
2007-07-19 02:48:24 -06:00
|
|
|
my $anon_struct_union = 0;
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
# match expressions used to find embedded type information
|
2017-03-30 14:11:28 -06:00
|
|
|
my $type_constant = '\b``([^\`]+)``\b';
|
|
|
|
my $type_constant2 = '\%([-_\w]+)';
|
2005-04-16 16:20:36 -06:00
|
|
|
my $type_func = '(\w+)\(\)';
|
scripts: kernel-doc: parse next structs/unions
There are several places within the Kernel tree with nested
structs/unions, like this one:
struct ingenic_cgu_clk_info {
const char *name;
enum {
CGU_CLK_NONE = 0,
CGU_CLK_EXT = BIT(0),
CGU_CLK_PLL = BIT(1),
CGU_CLK_GATE = BIT(2),
CGU_CLK_MUX = BIT(3),
CGU_CLK_MUX_GLITCHFREE = BIT(4),
CGU_CLK_DIV = BIT(5),
CGU_CLK_FIXDIV = BIT(6),
CGU_CLK_CUSTOM = BIT(7),
} type;
int parents[4];
union {
struct ingenic_cgu_pll_info pll;
struct {
struct ingenic_cgu_gate_info gate;
struct ingenic_cgu_mux_info mux;
struct ingenic_cgu_div_info div;
struct ingenic_cgu_fixdiv_info fixdiv;
};
struct ingenic_cgu_custom_info custom;
};
};
Currently, such struct is documented as:
**Definition**
::
struct ingenic_cgu_clk_info {
const char * name;
};
**Members**
``name``
name of the clock
With is obvioulsy wrong. It also generates an error:
drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum'
However, there's nothing wrong with this kernel-doc markup: everything
is documented there.
It makes sense to document all fields there. So, add a
way for the core to parse those structs.
With this patch, all documented fields will properly generate
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:13 -07:00
|
|
|
my $type_param = '\@(\w*(\.\w+)*(\.\.\.)?)';
|
2016-08-24 16:31:15 -06:00
|
|
|
my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
|
2005-04-16 16:20:36 -06:00
|
|
|
my $type_env = '(\$\w+)';
|
2017-01-02 08:22:27 -07:00
|
|
|
my $type_enum = '\&(enum\s*([_\w]+))';
|
|
|
|
my $type_struct = '\&(struct\s*([_\w]+))';
|
|
|
|
my $type_typedef = '\&(typedef\s*([_\w]+))';
|
|
|
|
my $type_union = '\&(union\s*([_\w]+))';
|
2017-01-02 08:22:26 -07:00
|
|
|
my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
|
2017-01-02 08:22:27 -07:00
|
|
|
my $type_fallback = '\&([_\w]+)';
|
2016-05-26 07:35:02 -06:00
|
|
|
my $type_member_func = $type_member . '\(\)';
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
# Output conversion substitutions.
|
|
|
|
# One for each output format
|
|
|
|
|
|
|
|
# these are pretty rough
|
2015-09-07 14:01:59 -06:00
|
|
|
my @highlights_man = (
|
|
|
|
[$type_constant, "\$1"],
|
2017-03-30 14:11:28 -06:00
|
|
|
[$type_constant2, "\$1"],
|
2015-09-07 14:01:59 -06:00
|
|
|
[$type_func, "\\\\fB\$1\\\\fP"],
|
2017-01-02 08:22:27 -07:00
|
|
|
[$type_enum, "\\\\fI\$1\\\\fP"],
|
2015-09-07 14:01:59 -06:00
|
|
|
[$type_struct, "\\\\fI\$1\\\\fP"],
|
2017-01-02 08:22:27 -07:00
|
|
|
[$type_typedef, "\\\\fI\$1\\\\fP"],
|
|
|
|
[$type_union, "\\\\fI\$1\\\\fP"],
|
2017-01-02 08:22:26 -07:00
|
|
|
[$type_param, "\\\\fI\$1\\\\fP"],
|
2017-01-02 08:22:27 -07:00
|
|
|
[$type_member, "\\\\fI\$1\$2\$3\\\\fP"],
|
|
|
|
[$type_fallback, "\\\\fI\$1\\\\fP"]
|
2015-09-07 14:01:59 -06:00
|
|
|
);
|
2005-04-16 16:20:36 -06:00
|
|
|
my $blankline_man = "";
|
|
|
|
|
2016-05-12 07:15:37 -06:00
|
|
|
# rst-mode
|
|
|
|
my @highlights_rst = (
|
|
|
|
[$type_constant, "``\$1``"],
|
2017-03-30 14:11:28 -06:00
|
|
|
[$type_constant2, "``\$1``"],
|
2016-05-26 07:35:02 -06:00
|
|
|
# Note: need to escape () to avoid func matching later
|
2017-01-02 08:22:26 -07:00
|
|
|
[$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
|
|
|
|
[$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
|
2016-08-24 16:31:15 -06:00
|
|
|
[$type_fp_param, "**\$1\\\\(\\\\)**"],
|
2016-05-26 02:28:16 -06:00
|
|
|
[$type_func, "\\:c\\:func\\:`\$1()`"],
|
2017-01-02 08:22:27 -07:00
|
|
|
[$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
|
|
|
|
[$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
|
|
|
|
[$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
|
|
|
|
[$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
|
2016-05-26 04:57:06 -06:00
|
|
|
# in rst this can refer to any type
|
2017-01-02 08:22:27 -07:00
|
|
|
[$type_fallback, "\\:c\\:type\\:`\$1`"],
|
2016-05-12 07:15:37 -06:00
|
|
|
[$type_param, "**\$1**"]
|
|
|
|
);
|
|
|
|
my $blankline_rst = "\n";
|
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
# read arguments
|
2009-06-09 09:50:38 -06:00
|
|
|
if ($#ARGV == -1) {
|
2005-04-16 16:20:36 -06:00
|
|
|
usage();
|
|
|
|
}
|
|
|
|
|
2011-01-05 17:28:43 -07:00
|
|
|
my $kernelversion;
|
|
|
|
my $dohighlight = "";
|
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
my $verbose = 0;
|
2017-12-18 05:30:11 -07:00
|
|
|
my $output_mode = "rst";
|
2012-10-04 18:15:08 -06:00
|
|
|
my $output_preformatted = 0;
|
2007-10-24 16:08:48 -06:00
|
|
|
my $no_doc_sections = 0;
|
2016-06-03 14:21:34 -06:00
|
|
|
my $enable_lineno = 0;
|
2017-12-18 05:30:11 -07:00
|
|
|
my @highlights = @highlights_rst;
|
|
|
|
my $blankline = $blankline_rst;
|
2005-04-16 16:20:36 -06:00
|
|
|
my $modulename = "Kernel API";
|
2016-05-29 13:19:35 -06:00
|
|
|
|
|
|
|
use constant {
|
|
|
|
OUTPUT_ALL => 0, # output all symbols and doc sections
|
|
|
|
OUTPUT_INCLUDE => 1, # output only specified symbols
|
|
|
|
OUTPUT_EXCLUDE => 2, # output everything except specified symbols
|
|
|
|
OUTPUT_EXPORTED => 3, # output exported symbols
|
|
|
|
OUTPUT_INTERNAL => 4, # output non-exported symbols
|
|
|
|
};
|
|
|
|
my $output_selection = OUTPUT_ALL;
|
2015-07-08 13:07:16 -06:00
|
|
|
my $show_not_found = 0;
|
|
|
|
|
2016-06-07 02:00:52 -06:00
|
|
|
my @export_file_list;
|
|
|
|
|
2015-07-08 13:07:16 -06:00
|
|
|
my @build_time;
|
|
|
|
if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
|
|
|
|
(my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
|
|
|
|
@build_time = gmtime($seconds);
|
|
|
|
} else {
|
|
|
|
@build_time = localtime;
|
|
|
|
}
|
|
|
|
|
2006-02-01 04:06:58 -07:00
|
|
|
my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
|
|
|
|
'July', 'August', 'September', 'October',
|
2015-07-08 13:07:16 -06:00
|
|
|
'November', 'December')[$build_time[4]] .
|
|
|
|
" " . ($build_time[5]+1900);
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2011-01-05 17:28:43 -07:00
|
|
|
# Essentially these are globals.
|
2009-06-09 09:50:38 -06:00
|
|
|
# They probably want to be tidied up, made more localised or something.
|
|
|
|
# CAVEAT EMPTOR! Some of the others I localised may not want to be, which
|
2005-04-16 16:20:36 -06:00
|
|
|
# could cause "use of undefined value" or other bugs.
|
2009-06-09 09:50:38 -06:00
|
|
|
my ($function, %function_table, %parametertypes, $declaration_purpose);
|
2016-06-03 14:21:34 -06:00
|
|
|
my $declaration_start_line;
|
2009-06-09 09:50:38 -06:00
|
|
|
my ($type, $declaration_name, $return_type);
|
2010-02-26 14:06:03 -07:00
|
|
|
my ($newsection, $newcontents, $prototype, $brcount, %source_map);
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2008-03-13 13:32:43 -06:00
|
|
|
if (defined($ENV{'KBUILD_VERBOSE'})) {
|
|
|
|
$verbose = "$ENV{'KBUILD_VERBOSE'}";
|
|
|
|
}
|
|
|
|
|
2006-02-01 04:06:58 -07:00
|
|
|
# Generated docbook code is inserted in a template at a point where
|
2005-04-16 16:20:36 -06:00
|
|
|
# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
|
|
|
|
# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
|
|
|
|
# We keep track of number of generated entries and generate a dummy
|
|
|
|
# if needs be to ensure the expanded template can be postprocessed
|
|
|
|
# into html.
|
|
|
|
my $section_counter = 0;
|
|
|
|
|
|
|
|
my $lineprefix="";
|
|
|
|
|
2016-05-26 05:56:05 -06:00
|
|
|
# Parser states
|
|
|
|
use constant {
|
|
|
|
STATE_NORMAL => 0, # normal code
|
|
|
|
STATE_NAME => 1, # looking for function name
|
|
|
|
STATE_FIELD => 2, # scanning field start
|
|
|
|
STATE_PROTO => 3, # scanning prototype
|
|
|
|
STATE_DOCBLOCK => 4, # documentation block
|
|
|
|
STATE_INLINE => 5, # gathering documentation outside main block
|
|
|
|
};
|
2005-04-16 16:20:36 -06:00
|
|
|
my $state;
|
2006-06-25 06:48:55 -06:00
|
|
|
my $in_doc_sect;
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2016-05-26 05:56:05 -06:00
|
|
|
# Inline documentation state
|
|
|
|
use constant {
|
|
|
|
STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)
|
|
|
|
STATE_INLINE_NAME => 1, # looking for member name (@foo:)
|
|
|
|
STATE_INLINE_TEXT => 2, # looking for member documentation
|
|
|
|
STATE_INLINE_END => 3, # done
|
|
|
|
STATE_INLINE_ERROR => 4, # error - Comment without header was found.
|
|
|
|
# Spit a warning as it's not
|
|
|
|
# proper kernel-doc and ignore the rest.
|
|
|
|
};
|
|
|
|
my $inline_doc_state;
|
2015-08-04 06:04:08 -06:00
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
#declaration types: can be
|
|
|
|
# 'function', 'struct', 'union', 'enum', 'typedef'
|
|
|
|
my $decl_type;
|
|
|
|
|
|
|
|
my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
|
|
|
|
my $doc_end = '\*/';
|
|
|
|
my $doc_com = '\s*\*\s*';
|
2012-10-04 18:15:10 -06:00
|
|
|
my $doc_com_body = '\s*\* ?';
|
2009-06-09 09:50:38 -06:00
|
|
|
my $doc_decl = $doc_com . '(\w+)';
|
kernel-doc: limit the "section header:" detection to a select few
kernel-doc currently identifies anything matching "section header:"
(specifically a string of word characters and spaces followed by a
colon) as a new section in the documentation comment, and renders the
section header accordingly.
Unfortunately, this turns all uses of colon into sections, mostly
unintentionally. Considering the output, erroneously creating sections
when not intended is always worse than erroneously not creating sections
when intended. For example, a line with "http://example.com" turns into
a "http" heading followed by "//example.com" in normal text style, which
is quite ugly. OTOH, "WARNING: Beware of the Leopard" is just fine even
if "WARNING" does not turn into a heading.
It is virtually impossible to change all the kernel-doc comments, either
way. The compromise is to pick the most commonly used and depended on
section headers (with variants) and accept them as section headers.
The accepted section headers are, case insensitive:
* description:
* context:
* return:
* returns:
Additionally, case sensitive:
* @return:
All of the above are commonly used in the kernel-doc comments, and will
result in worse output if not identified as section headers. Also,
kernel-doc already has some special handling for all of them, so there's
nothing particularly controversial in adding more special treatment for
them.
While at it, improve the whitespace handling surrounding section
names. Do not consider the whitespace as part of the name.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-29 02:35:28 -06:00
|
|
|
# @params and a strictly limited set of supported section names
|
2016-06-09 13:35:05 -06:00
|
|
|
my $doc_sect = $doc_com .
|
2016-08-26 07:14:08 -06:00
|
|
|
'\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
|
2012-10-04 18:15:10 -06:00
|
|
|
my $doc_content = $doc_com_body . '(.*)';
|
2009-06-09 09:50:38 -06:00
|
|
|
my $doc_block = $doc_com . 'DOC:\s*(.*)?';
|
2016-05-26 05:56:05 -06:00
|
|
|
my $doc_inline_start = '^\s*/\*\*\s*$';
|
|
|
|
my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
|
|
|
|
my $doc_inline_end = '^\s*\*/\s*$';
|
2016-11-16 08:26:16 -07:00
|
|
|
my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
|
2016-01-21 04:05:22 -07:00
|
|
|
my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
my %parameterdescs;
|
2016-06-03 14:21:34 -06:00
|
|
|
my %parameterdesc_start_lines;
|
2005-04-16 16:20:36 -06:00
|
|
|
my @parameterlist;
|
|
|
|
my %sections;
|
|
|
|
my @sectionlist;
|
2016-06-03 14:21:34 -06:00
|
|
|
my %section_start_lines;
|
2008-12-19 09:49:30 -07:00
|
|
|
my $sectcheck;
|
|
|
|
my $struct_actual;
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
my $contents = "";
|
2016-06-03 14:21:34 -06:00
|
|
|
my $new_start_line = 0;
|
kernel-doc: limit the "section header:" detection to a select few
kernel-doc currently identifies anything matching "section header:"
(specifically a string of word characters and spaces followed by a
colon) as a new section in the documentation comment, and renders the
section header accordingly.
Unfortunately, this turns all uses of colon into sections, mostly
unintentionally. Considering the output, erroneously creating sections
when not intended is always worse than erroneously not creating sections
when intended. For example, a line with "http://example.com" turns into
a "http" heading followed by "//example.com" in normal text style, which
is quite ugly. OTOH, "WARNING: Beware of the Leopard" is just fine even
if "WARNING" does not turn into a heading.
It is virtually impossible to change all the kernel-doc comments, either
way. The compromise is to pick the most commonly used and depended on
section headers (with variants) and accept them as section headers.
The accepted section headers are, case insensitive:
* description:
* context:
* return:
* returns:
Additionally, case sensitive:
* @return:
All of the above are commonly used in the kernel-doc comments, and will
result in worse output if not identified as section headers. Also,
kernel-doc already has some special handling for all of them, so there's
nothing particularly controversial in adding more special treatment for
them.
While at it, improve the whitespace handling surrounding section
names. Do not consider the whitespace as part of the name.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-29 02:35:28 -06:00
|
|
|
|
|
|
|
# the canonical section names. see also $doc_sect above.
|
2005-04-16 16:20:36 -06:00
|
|
|
my $section_default = "Description"; # default section
|
|
|
|
my $section_intro = "Introduction";
|
|
|
|
my $section = $section_default;
|
|
|
|
my $section_context = "Context";
|
2012-11-26 14:22:27 -07:00
|
|
|
my $section_return = "Return";
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
my $undescribed = "-- undescribed --";
|
|
|
|
|
|
|
|
reset_state();
|
|
|
|
|
2017-12-18 05:30:10 -07:00
|
|
|
while ($ARGV[0] =~ m/^--?(.*)/) {
|
|
|
|
my $cmd = $1;
|
|
|
|
shift @ARGV;
|
|
|
|
if ($cmd eq "man") {
|
2005-04-16 16:20:36 -06:00
|
|
|
$output_mode = "man";
|
2015-09-07 14:01:59 -06:00
|
|
|
@highlights = @highlights_man;
|
2005-04-16 16:20:36 -06:00
|
|
|
$blankline = $blankline_man;
|
2017-12-18 05:30:10 -07:00
|
|
|
} elsif ($cmd eq "rst") {
|
2016-05-12 07:15:37 -06:00
|
|
|
$output_mode = "rst";
|
|
|
|
@highlights = @highlights_rst;
|
|
|
|
$blankline = $blankline_rst;
|
2017-12-18 05:30:10 -07:00
|
|
|
} elsif ($cmd eq "none") {
|
2017-11-20 11:40:40 -07:00
|
|
|
$output_mode = "none";
|
2017-12-18 05:30:10 -07:00
|
|
|
} elsif ($cmd eq "module") { # not needed for XML, inherits from calling document
|
2005-04-16 16:20:36 -06:00
|
|
|
$modulename = shift @ARGV;
|
2017-12-18 05:30:10 -07:00
|
|
|
} elsif ($cmd eq "function") { # to only output specific functions
|
2016-05-29 13:19:35 -06:00
|
|
|
$output_selection = OUTPUT_INCLUDE;
|
2005-04-16 16:20:36 -06:00
|
|
|
$function = shift @ARGV;
|
|
|
|
$function_table{$function} = 1;
|
2017-12-18 05:30:10 -07:00
|
|
|
} elsif ($cmd eq "nofunction") { # output all except specific functions
|
2016-05-29 13:19:35 -06:00
|
|
|
$output_selection = OUTPUT_EXCLUDE;
|
2005-04-16 16:20:36 -06:00
|
|
|
$function = shift @ARGV;
|
|
|
|
$function_table{$function} = 1;
|
2017-12-18 05:30:10 -07:00
|
|
|
} elsif ($cmd eq "export") { # only exported symbols
|
2016-05-29 13:19:35 -06:00
|
|
|
$output_selection = OUTPUT_EXPORTED;
|
2016-06-07 01:29:59 -06:00
|
|
|
%function_table = ();
|
2017-12-18 05:30:10 -07:00
|
|
|
} elsif ($cmd eq "internal") { # only non-exported symbols
|
2016-05-29 13:19:35 -06:00
|
|
|
$output_selection = OUTPUT_INTERNAL;
|
2016-06-07 01:29:59 -06:00
|
|
|
%function_table = ();
|
2017-12-18 05:30:10 -07:00
|
|
|
} elsif ($cmd eq "export-file") {
|
2016-06-07 02:00:52 -06:00
|
|
|
my $file = shift @ARGV;
|
|
|
|
push(@export_file_list, $file);
|
2017-12-18 05:30:10 -07:00
|
|
|
} elsif ($cmd eq "v") {
|
2005-04-16 16:20:36 -06:00
|
|
|
$verbose = 1;
|
2017-12-18 05:30:10 -07:00
|
|
|
} elsif (($cmd eq "h") || ($cmd eq "help")) {
|
2005-04-16 16:20:36 -06:00
|
|
|
usage();
|
2017-12-18 05:30:10 -07:00
|
|
|
} elsif ($cmd eq 'no-doc-sections') {
|
2007-10-24 16:08:48 -06:00
|
|
|
$no_doc_sections = 1;
|
2017-12-18 05:30:10 -07:00
|
|
|
} elsif ($cmd eq 'enable-lineno') {
|
2016-06-03 14:21:34 -06:00
|
|
|
$enable_lineno = 1;
|
2017-12-18 05:30:10 -07:00
|
|
|
} elsif ($cmd eq 'show-not-found') {
|
2013-11-12 16:11:12 -07:00
|
|
|
$show_not_found = 1;
|
2017-12-18 05:30:10 -07:00
|
|
|
} else {
|
|
|
|
# Unknown argument
|
|
|
|
usage();
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2011-01-05 17:28:43 -07:00
|
|
|
# continue execution near EOF;
|
|
|
|
|
2007-05-08 01:30:54 -06:00
|
|
|
# get kernel version from env
|
|
|
|
sub get_kernel_version() {
|
2007-10-24 16:08:48 -06:00
|
|
|
my $version = 'unknown kernel version';
|
2007-05-08 01:30:54 -06:00
|
|
|
|
|
|
|
if (defined($ENV{'KERNELVERSION'})) {
|
|
|
|
$version = $ENV{'KERNELVERSION'};
|
|
|
|
}
|
|
|
|
return $version;
|
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2016-06-03 14:21:34 -06:00
|
|
|
#
|
|
|
|
sub print_lineno {
|
|
|
|
my $lineno = shift;
|
|
|
|
if ($enable_lineno && defined($lineno)) {
|
|
|
|
print "#define LINENO " . $lineno . "\n";
|
|
|
|
}
|
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
##
|
|
|
|
# dumps section contents to arrays/hashes intended for that purpose.
|
|
|
|
#
|
|
|
|
sub dump_section {
|
2008-04-28 03:16:34 -06:00
|
|
|
my $file = shift;
|
2005-04-16 16:20:36 -06:00
|
|
|
my $name = shift;
|
|
|
|
my $contents = join "\n", @_;
|
|
|
|
|
2016-05-25 23:57:29 -06:00
|
|
|
if ($name =~ m/$type_param/) {
|
2005-04-16 16:20:36 -06:00
|
|
|
$name = $1;
|
|
|
|
$parameterdescs{$name} = $contents;
|
2008-12-19 09:49:30 -07:00
|
|
|
$sectcheck = $sectcheck . $name . " ";
|
2016-06-03 14:21:34 -06:00
|
|
|
$parameterdesc_start_lines{$name} = $new_start_line;
|
|
|
|
$new_start_line = 0;
|
2008-12-01 14:14:03 -07:00
|
|
|
} elsif ($name eq "@\.\.\.") {
|
|
|
|
$name = "...";
|
|
|
|
$parameterdescs{$name} = $contents;
|
2008-12-19 09:49:30 -07:00
|
|
|
$sectcheck = $sectcheck . $name . " ";
|
2016-06-03 14:21:34 -06:00
|
|
|
$parameterdesc_start_lines{$name} = $new_start_line;
|
|
|
|
$new_start_line = 0;
|
2005-04-16 16:20:36 -06:00
|
|
|
} else {
|
2008-04-28 03:16:34 -06:00
|
|
|
if (defined($sections{$name}) && ($sections{$name} ne "")) {
|
2016-06-10 02:14:05 -06:00
|
|
|
# Only warn on user specified duplicate section names.
|
|
|
|
if ($name ne $section_default) {
|
|
|
|
print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
|
|
|
|
++$warnings;
|
|
|
|
}
|
2016-05-29 00:40:44 -06:00
|
|
|
$sections{$name} .= $contents;
|
|
|
|
} else {
|
|
|
|
$sections{$name} = $contents;
|
|
|
|
push @sectionlist, $name;
|
2016-06-03 14:21:34 -06:00
|
|
|
$section_start_lines{$name} = $new_start_line;
|
|
|
|
$new_start_line = 0;
|
2008-04-28 03:16:34 -06:00
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2007-10-24 16:08:48 -06:00
|
|
|
##
|
|
|
|
# dump DOC: section after checking that it should go out
|
|
|
|
#
|
|
|
|
sub dump_doc_section {
|
2008-04-28 03:16:34 -06:00
|
|
|
my $file = shift;
|
2007-10-24 16:08:48 -06:00
|
|
|
my $name = shift;
|
|
|
|
my $contents = join "\n", @_;
|
|
|
|
|
2007-10-24 16:08:48 -06:00
|
|
|
if ($no_doc_sections) {
|
|
|
|
return;
|
|
|
|
}
|
|
|
|
|
2016-05-29 13:19:35 -06:00
|
|
|
if (($output_selection == OUTPUT_ALL) ||
|
|
|
|
($output_selection == OUTPUT_INCLUDE &&
|
|
|
|
defined($function_table{$name})) ||
|
|
|
|
($output_selection == OUTPUT_EXCLUDE &&
|
|
|
|
!defined($function_table{$name})))
|
2007-10-24 16:08:48 -06:00
|
|
|
{
|
2008-04-28 03:16:34 -06:00
|
|
|
dump_section($file, $name, $contents);
|
2007-10-24 16:08:48 -06:00
|
|
|
output_blockhead({'sectionlist' => \@sectionlist,
|
|
|
|
'sections' => \%sections,
|
|
|
|
'module' => $modulename,
|
2016-05-29 13:19:35 -06:00
|
|
|
'content-only' => ($output_selection != OUTPUT_ALL), });
|
2007-10-24 16:08:48 -06:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
##
|
|
|
|
# output function
|
|
|
|
#
|
|
|
|
# parameterdescs, a hash.
|
|
|
|
# function => "function name"
|
|
|
|
# parameterlist => @list of parameters
|
|
|
|
# parameterdescs => %parameter descriptions
|
|
|
|
# sectionlist => @list of sections
|
2007-02-10 02:46:04 -07:00
|
|
|
# sections => %section descriptions
|
2006-02-01 04:06:58 -07:00
|
|
|
#
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
sub output_highlight {
|
|
|
|
my $contents = join "\n",@_;
|
|
|
|
my $line;
|
|
|
|
|
|
|
|
# DEBUG
|
|
|
|
# if (!defined $contents) {
|
|
|
|
# use Carp;
|
|
|
|
# confess "output_highlight got called with no args?\n";
|
|
|
|
# }
|
|
|
|
|
2007-05-08 01:29:51 -06:00
|
|
|
# print STDERR "contents b4:$contents\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
eval $dohighlight;
|
|
|
|
die $@ if $@;
|
2007-05-08 01:29:51 -06:00
|
|
|
# print STDERR "contents af:$contents\n";
|
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
foreach $line (split "\n", $contents) {
|
2012-10-04 18:15:10 -06:00
|
|
|
if (! $output_preformatted) {
|
|
|
|
$line =~ s/^\s*//;
|
|
|
|
}
|
2007-05-08 01:24:39 -06:00
|
|
|
if ($line eq ""){
|
2012-10-04 18:15:08 -06:00
|
|
|
if (! $output_preformatted) {
|
|
|
|
print $lineprefix, local_unescape($blankline);
|
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
} else {
|
2007-05-08 01:24:39 -06:00
|
|
|
$line =~ s/\\\\\\/\&/g;
|
2007-07-19 02:48:25 -06:00
|
|
|
if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
|
|
|
|
print "\\&$line";
|
|
|
|
} else {
|
|
|
|
print $lineprefix, $line;
|
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
|
|
|
print "\n";
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
##
|
|
|
|
# output function in man
|
|
|
|
sub output_function_man(%) {
|
|
|
|
my %args = %{$_[0]};
|
|
|
|
my ($parameter, $section);
|
|
|
|
my $count;
|
|
|
|
|
|
|
|
print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
|
|
|
|
|
|
|
|
print ".SH NAME\n";
|
2009-06-09 09:50:38 -06:00
|
|
|
print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
print ".SH SYNOPSIS\n";
|
2007-02-10 02:46:04 -07:00
|
|
|
if ($args{'functiontype'} ne "") {
|
2009-06-09 09:50:38 -06:00
|
|
|
print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
|
2007-02-10 02:46:04 -07:00
|
|
|
} else {
|
2009-06-09 09:50:38 -06:00
|
|
|
print ".B \"" . $args{'function'} . "\n";
|
2007-02-10 02:46:04 -07:00
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
$count = 0;
|
|
|
|
my $parenth = "(";
|
|
|
|
my $post = ",";
|
|
|
|
foreach my $parameter (@{$args{'parameterlist'}}) {
|
|
|
|
if ($count == $#{$args{'parameterlist'}}) {
|
|
|
|
$post = ");";
|
|
|
|
}
|
|
|
|
$type = $args{'parametertypes'}{$parameter};
|
|
|
|
if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
|
|
|
|
# pointer-to-function
|
2009-06-09 09:50:38 -06:00
|
|
|
print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
} else {
|
|
|
|
$type =~ s/([^\*])$/$1 /;
|
2009-06-09 09:50:38 -06:00
|
|
|
print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
|
|
|
$count++;
|
|
|
|
$parenth = "";
|
|
|
|
}
|
|
|
|
|
|
|
|
print ".SH ARGUMENTS\n";
|
|
|
|
foreach $parameter (@{$args{'parameterlist'}}) {
|
|
|
|
my $parameter_name = $parameter;
|
|
|
|
$parameter_name =~ s/\[.*//;
|
|
|
|
|
2009-06-09 09:50:38 -06:00
|
|
|
print ".IP \"" . $parameter . "\" 12\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
output_highlight($args{'parameterdescs'}{$parameter_name});
|
|
|
|
}
|
|
|
|
foreach $section (@{$args{'sectionlist'}}) {
|
|
|
|
print ".SH \"", uc $section, "\"\n";
|
|
|
|
output_highlight($args{'sections'}{$section});
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
##
|
|
|
|
# output enum in man
|
|
|
|
sub output_enum_man(%) {
|
|
|
|
my %args = %{$_[0]};
|
|
|
|
my ($parameter, $section);
|
|
|
|
my $count;
|
|
|
|
|
|
|
|
print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
|
|
|
|
|
|
|
|
print ".SH NAME\n";
|
2009-06-09 09:50:38 -06:00
|
|
|
print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
print ".SH SYNOPSIS\n";
|
2009-06-09 09:50:38 -06:00
|
|
|
print "enum " . $args{'enum'} . " {\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
$count = 0;
|
|
|
|
foreach my $parameter (@{$args{'parameterlist'}}) {
|
2007-05-08 01:24:39 -06:00
|
|
|
print ".br\n.BI \" $parameter\"\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
if ($count == $#{$args{'parameterlist'}}) {
|
|
|
|
print "\n};\n";
|
|
|
|
last;
|
|
|
|
}
|
|
|
|
else {
|
|
|
|
print ", \n.br\n";
|
|
|
|
}
|
|
|
|
$count++;
|
|
|
|
}
|
|
|
|
|
|
|
|
print ".SH Constants\n";
|
|
|
|
foreach $parameter (@{$args{'parameterlist'}}) {
|
|
|
|
my $parameter_name = $parameter;
|
|
|
|
$parameter_name =~ s/\[.*//;
|
|
|
|
|
2009-06-09 09:50:38 -06:00
|
|
|
print ".IP \"" . $parameter . "\" 12\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
output_highlight($args{'parameterdescs'}{$parameter_name});
|
|
|
|
}
|
|
|
|
foreach $section (@{$args{'sectionlist'}}) {
|
|
|
|
print ".SH \"$section\"\n";
|
|
|
|
output_highlight($args{'sections'}{$section});
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
##
|
|
|
|
# output struct in man
|
|
|
|
sub output_struct_man(%) {
|
|
|
|
my %args = %{$_[0]};
|
|
|
|
my ($parameter, $section);
|
|
|
|
|
2009-06-09 09:50:38 -06:00
|
|
|
print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
print ".SH NAME\n";
|
2009-06-09 09:50:38 -06:00
|
|
|
print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
|
scripts: kernel-doc: parse next structs/unions
There are several places within the Kernel tree with nested
structs/unions, like this one:
struct ingenic_cgu_clk_info {
const char *name;
enum {
CGU_CLK_NONE = 0,
CGU_CLK_EXT = BIT(0),
CGU_CLK_PLL = BIT(1),
CGU_CLK_GATE = BIT(2),
CGU_CLK_MUX = BIT(3),
CGU_CLK_MUX_GLITCHFREE = BIT(4),
CGU_CLK_DIV = BIT(5),
CGU_CLK_FIXDIV = BIT(6),
CGU_CLK_CUSTOM = BIT(7),
} type;
int parents[4];
union {
struct ingenic_cgu_pll_info pll;
struct {
struct ingenic_cgu_gate_info gate;
struct ingenic_cgu_mux_info mux;
struct ingenic_cgu_div_info div;
struct ingenic_cgu_fixdiv_info fixdiv;
};
struct ingenic_cgu_custom_info custom;
};
};
Currently, such struct is documented as:
**Definition**
::
struct ingenic_cgu_clk_info {
const char * name;
};
**Members**
``name``
name of the clock
With is obvioulsy wrong. It also generates an error:
drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum'
However, there's nothing wrong with this kernel-doc markup: everything
is documented there.
It makes sense to document all fields there. So, add a
way for the core to parse those structs.
With this patch, all documented fields will properly generate
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:13 -07:00
|
|
|
my $declaration = $args{'definition'};
|
|
|
|
$declaration =~ s/\t/ /g;
|
|
|
|
$declaration =~ s/\n/"\n.br\n.BI \"/g;
|
2005-04-16 16:20:36 -06:00
|
|
|
print ".SH SYNOPSIS\n";
|
2009-06-09 09:50:38 -06:00
|
|
|
print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
|
scripts: kernel-doc: parse next structs/unions
There are several places within the Kernel tree with nested
structs/unions, like this one:
struct ingenic_cgu_clk_info {
const char *name;
enum {
CGU_CLK_NONE = 0,
CGU_CLK_EXT = BIT(0),
CGU_CLK_PLL = BIT(1),
CGU_CLK_GATE = BIT(2),
CGU_CLK_MUX = BIT(3),
CGU_CLK_MUX_GLITCHFREE = BIT(4),
CGU_CLK_DIV = BIT(5),
CGU_CLK_FIXDIV = BIT(6),
CGU_CLK_CUSTOM = BIT(7),
} type;
int parents[4];
union {
struct ingenic_cgu_pll_info pll;
struct {
struct ingenic_cgu_gate_info gate;
struct ingenic_cgu_mux_info mux;
struct ingenic_cgu_div_info div;
struct ingenic_cgu_fixdiv_info fixdiv;
};
struct ingenic_cgu_custom_info custom;
};
};
Currently, such struct is documented as:
**Definition**
::
struct ingenic_cgu_clk_info {
const char * name;
};
**Members**
``name``
name of the clock
With is obvioulsy wrong. It also generates an error:
drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum'
However, there's nothing wrong with this kernel-doc markup: everything
is documented there.
It makes sense to document all fields there. So, add a
way for the core to parse those structs.
With this patch, all documented fields will properly generate
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:13 -07:00
|
|
|
print ".BI \"$declaration\n};\n.br\n\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2006-06-25 06:49:14 -06:00
|
|
|
print ".SH Members\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
foreach $parameter (@{$args{'parameterlist'}}) {
|
|
|
|
($parameter =~ /^#/) && next;
|
|
|
|
|
|
|
|
my $parameter_name = $parameter;
|
|
|
|
$parameter_name =~ s/\[.*//;
|
|
|
|
|
2007-05-08 01:24:39 -06:00
|
|
|
($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
|
2009-06-09 09:50:38 -06:00
|
|
|
print ".IP \"" . $parameter . "\" 12\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
output_highlight($args{'parameterdescs'}{$parameter_name});
|
|
|
|
}
|
|
|
|
foreach $section (@{$args{'sectionlist'}}) {
|
|
|
|
print ".SH \"$section\"\n";
|
|
|
|
output_highlight($args{'sections'}{$section});
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
##
|
|
|
|
# output typedef in man
|
|
|
|
sub output_typedef_man(%) {
|
|
|
|
my %args = %{$_[0]};
|
|
|
|
my ($parameter, $section);
|
|
|
|
|
|
|
|
print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
|
|
|
|
|
|
|
|
print ".SH NAME\n";
|
2009-06-09 09:50:38 -06:00
|
|
|
print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
foreach $section (@{$args{'sectionlist'}}) {
|
|
|
|
print ".SH \"$section\"\n";
|
|
|
|
output_highlight($args{'sections'}{$section});
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2007-10-24 16:08:48 -06:00
|
|
|
sub output_blockhead_man(%) {
|
2005-04-16 16:20:36 -06:00
|
|
|
my %args = %{$_[0]};
|
|
|
|
my ($parameter, $section);
|
|
|
|
my $count;
|
|
|
|
|
|
|
|
print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
|
|
|
|
|
|
|
|
foreach $section (@{$args{'sectionlist'}}) {
|
|
|
|
print ".SH \"$section\"\n";
|
|
|
|
output_highlight($args{'sections'}{$section});
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2016-05-12 07:15:37 -06:00
|
|
|
##
|
|
|
|
# output in restructured text
|
|
|
|
#
|
|
|
|
|
|
|
|
#
|
|
|
|
# This could use some work; it's used to output the DOC: sections, and
|
|
|
|
# starts by putting out the name of the doc section itself, but that tends
|
|
|
|
# to duplicate a header already in the template file.
|
|
|
|
#
|
|
|
|
sub output_blockhead_rst(%) {
|
|
|
|
my %args = %{$_[0]};
|
|
|
|
my ($parameter, $section);
|
|
|
|
|
|
|
|
foreach $section (@{$args{'sectionlist'}}) {
|
2016-05-29 13:27:35 -06:00
|
|
|
if ($output_selection != OUTPUT_INCLUDE) {
|
|
|
|
print "**$section**\n\n";
|
|
|
|
}
|
2016-06-03 14:21:34 -06:00
|
|
|
print_lineno($section_start_lines{$section});
|
2016-05-12 07:15:37 -06:00
|
|
|
output_highlight_rst($args{'sections'}{$section});
|
|
|
|
print "\n";
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
sub output_highlight_rst {
|
|
|
|
my $contents = join "\n",@_;
|
|
|
|
my $line;
|
|
|
|
|
|
|
|
# undo the evil effects of xml_escape() earlier
|
|
|
|
$contents = xml_unescape($contents);
|
|
|
|
|
|
|
|
eval $dohighlight;
|
|
|
|
die $@ if $@;
|
|
|
|
|
|
|
|
foreach $line (split "\n", $contents) {
|
2016-05-26 13:04:33 -06:00
|
|
|
print $lineprefix . $line . "\n";
|
2016-05-12 07:15:37 -06:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
sub output_function_rst(%) {
|
|
|
|
my %args = %{$_[0]};
|
|
|
|
my ($parameter, $section);
|
2016-05-26 08:18:17 -06:00
|
|
|
my $oldprefix = $lineprefix;
|
docs-rst: kernel-doc: fix typedef output in RST format
When using a typedef function like this one:
typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);
The Sphinx C domain expects it to create a c:type: reference,
as that's the way it creates the type references when parsing
a c:function:: declaration.
So, a declaration like:
.. c:function:: bool v4l2_valid_dv_timings (const struct v4l2_dv_timings * t, const struct v4l2_dv_timings_cap * cap, v4l2_check_dv_timings_fnc fnc, void * fnc_handle)
Will create a cross reference for :c:type:`v4l2_check_dv_timings_fnc`.
So, when outputting such typedefs in RST format, we need to handle
this special case, as otherwise it will produce those warnings:
./include/media/v4l2-dv-timings.h:43: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
./include/media/v4l2-dv-timings.h:60: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
./include/media/v4l2-dv-timings.h:81: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
So, change the kernel-doc script to produce a RST output for the
above typedef as:
.. c:type:: v4l2_check_dv_timings_fnc
**Typedef**: timings check callback
**Syntax**
``bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);``
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-30 17:20:58 -06:00
|
|
|
my $start = "";
|
|
|
|
|
|
|
|
if ($args{'typedef'}) {
|
|
|
|
print ".. c:type:: ". $args{'function'} . "\n\n";
|
|
|
|
print_lineno($declaration_start_line);
|
|
|
|
print " **Typedef**: ";
|
|
|
|
$lineprefix = "";
|
|
|
|
output_highlight_rst($args{'purpose'});
|
|
|
|
$start = "\n\n**Syntax**\n\n ``";
|
|
|
|
} else {
|
|
|
|
print ".. c:function:: ";
|
|
|
|
}
|
2016-05-12 07:15:37 -06:00
|
|
|
if ($args{'functiontype'} ne "") {
|
docs-rst: kernel-doc: fix typedef output in RST format
When using a typedef function like this one:
typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);
The Sphinx C domain expects it to create a c:type: reference,
as that's the way it creates the type references when parsing
a c:function:: declaration.
So, a declaration like:
.. c:function:: bool v4l2_valid_dv_timings (const struct v4l2_dv_timings * t, const struct v4l2_dv_timings_cap * cap, v4l2_check_dv_timings_fnc fnc, void * fnc_handle)
Will create a cross reference for :c:type:`v4l2_check_dv_timings_fnc`.
So, when outputting such typedefs in RST format, we need to handle
this special case, as otherwise it will produce those warnings:
./include/media/v4l2-dv-timings.h:43: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
./include/media/v4l2-dv-timings.h:60: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
./include/media/v4l2-dv-timings.h:81: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
So, change the kernel-doc script to produce a RST output for the
above typedef as:
.. c:type:: v4l2_check_dv_timings_fnc
**Typedef**: timings check callback
**Syntax**
``bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);``
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-30 17:20:58 -06:00
|
|
|
$start .= $args{'functiontype'} . " " . $args{'function'} . " (";
|
2016-05-12 07:15:37 -06:00
|
|
|
} else {
|
docs-rst: kernel-doc: fix typedef output in RST format
When using a typedef function like this one:
typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);
The Sphinx C domain expects it to create a c:type: reference,
as that's the way it creates the type references when parsing
a c:function:: declaration.
So, a declaration like:
.. c:function:: bool v4l2_valid_dv_timings (const struct v4l2_dv_timings * t, const struct v4l2_dv_timings_cap * cap, v4l2_check_dv_timings_fnc fnc, void * fnc_handle)
Will create a cross reference for :c:type:`v4l2_check_dv_timings_fnc`.
So, when outputting such typedefs in RST format, we need to handle
this special case, as otherwise it will produce those warnings:
./include/media/v4l2-dv-timings.h:43: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
./include/media/v4l2-dv-timings.h:60: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
./include/media/v4l2-dv-timings.h:81: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
So, change the kernel-doc script to produce a RST output for the
above typedef as:
.. c:type:: v4l2_check_dv_timings_fnc
**Typedef**: timings check callback
**Syntax**
``bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);``
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-30 17:20:58 -06:00
|
|
|
$start .= $args{'function'} . " (";
|
2016-05-12 07:15:37 -06:00
|
|
|
}
|
|
|
|
print $start;
|
|
|
|
|
|
|
|
my $count = 0;
|
|
|
|
foreach my $parameter (@{$args{'parameterlist'}}) {
|
|
|
|
if ($count ne 0) {
|
|
|
|
print ", ";
|
|
|
|
}
|
|
|
|
$count++;
|
|
|
|
$type = $args{'parametertypes'}{$parameter};
|
doc-rst: kernel-doc: fix handling of address_space tags
The RST cpp:function handler is very pedantic: it doesn't allow any
macros like __user on it:
Documentation/media/kapi/dtv-core.rst:28: WARNING: Error when parsing function declaration.
If the function has no return type:
Error in declarator or parameters and qualifiers
Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 8]
ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
--------^
If the function has a return type:
Error in declarator or parameters and qualifiers
If pointer to member declarator:
Invalid definition: Expected '::' in pointer to member (function). [error at 37]
ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
-------------------------------------^
If declarator-id:
Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "*". [error at 102]
ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
------------------------------------------------------------------------------------------------------^
So, we have to remove it from the function prototype.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-07-22 08:46:36 -06:00
|
|
|
|
2016-05-12 07:15:37 -06:00
|
|
|
if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
|
|
|
|
# pointer-to-function
|
|
|
|
print $1 . $parameter . ") (" . $2;
|
|
|
|
} else {
|
|
|
|
print $type . " " . $parameter;
|
|
|
|
}
|
|
|
|
}
|
docs-rst: kernel-doc: fix typedef output in RST format
When using a typedef function like this one:
typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);
The Sphinx C domain expects it to create a c:type: reference,
as that's the way it creates the type references when parsing
a c:function:: declaration.
So, a declaration like:
.. c:function:: bool v4l2_valid_dv_timings (const struct v4l2_dv_timings * t, const struct v4l2_dv_timings_cap * cap, v4l2_check_dv_timings_fnc fnc, void * fnc_handle)
Will create a cross reference for :c:type:`v4l2_check_dv_timings_fnc`.
So, when outputting such typedefs in RST format, we need to handle
this special case, as otherwise it will produce those warnings:
./include/media/v4l2-dv-timings.h:43: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
./include/media/v4l2-dv-timings.h:60: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
./include/media/v4l2-dv-timings.h:81: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
So, change the kernel-doc script to produce a RST output for the
above typedef as:
.. c:type:: v4l2_check_dv_timings_fnc
**Typedef**: timings check callback
**Syntax**
``bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);``
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-30 17:20:58 -06:00
|
|
|
if ($args{'typedef'}) {
|
|
|
|
print ");``\n\n";
|
|
|
|
} else {
|
|
|
|
print ")\n\n";
|
|
|
|
print_lineno($declaration_start_line);
|
|
|
|
$lineprefix = " ";
|
|
|
|
output_highlight_rst($args{'purpose'});
|
|
|
|
print "\n";
|
|
|
|
}
|
2016-05-12 07:15:37 -06:00
|
|
|
|
2016-05-26 09:30:27 -06:00
|
|
|
print "**Parameters**\n\n";
|
|
|
|
$lineprefix = " ";
|
2016-05-12 07:15:37 -06:00
|
|
|
foreach $parameter (@{$args{'parameterlist'}}) {
|
|
|
|
my $parameter_name = $parameter;
|
2017-01-09 13:11:57 -07:00
|
|
|
$parameter_name =~ s/\[.*//;
|
2016-05-12 07:15:37 -06:00
|
|
|
$type = $args{'parametertypes'}{$parameter};
|
|
|
|
|
|
|
|
if ($type ne "") {
|
2016-05-26 09:30:27 -06:00
|
|
|
print "``$type $parameter``\n";
|
2016-05-12 07:15:37 -06:00
|
|
|
} else {
|
2016-05-26 09:30:27 -06:00
|
|
|
print "``$parameter``\n";
|
2016-05-12 07:15:37 -06:00
|
|
|
}
|
2016-06-03 14:21:34 -06:00
|
|
|
|
|
|
|
print_lineno($parameterdesc_start_lines{$parameter_name});
|
|
|
|
|
2016-05-19 11:32:48 -06:00
|
|
|
if (defined($args{'parameterdescs'}{$parameter_name}) &&
|
|
|
|
$args{'parameterdescs'}{$parameter_name} ne $undescribed) {
|
2016-05-12 07:15:37 -06:00
|
|
|
output_highlight_rst($args{'parameterdescs'}{$parameter_name});
|
|
|
|
} else {
|
2016-05-27 15:48:17 -06:00
|
|
|
print " *undescribed*\n";
|
2016-05-12 07:15:37 -06:00
|
|
|
}
|
|
|
|
print "\n";
|
|
|
|
}
|
2016-05-26 08:18:17 -06:00
|
|
|
|
|
|
|
$lineprefix = $oldprefix;
|
2016-05-12 07:15:37 -06:00
|
|
|
output_section_rst(@_);
|
|
|
|
}
|
|
|
|
|
|
|
|
sub output_section_rst(%) {
|
|
|
|
my %args = %{$_[0]};
|
|
|
|
my $section;
|
|
|
|
my $oldprefix = $lineprefix;
|
2016-05-26 09:30:27 -06:00
|
|
|
$lineprefix = "";
|
2016-05-12 07:15:37 -06:00
|
|
|
|
|
|
|
foreach $section (@{$args{'sectionlist'}}) {
|
2016-05-26 09:30:27 -06:00
|
|
|
print "**$section**\n\n";
|
2016-06-03 14:21:34 -06:00
|
|
|
print_lineno($section_start_lines{$section});
|
2016-05-12 07:15:37 -06:00
|
|
|
output_highlight_rst($args{'sections'}{$section});
|
|
|
|
print "\n";
|
|
|
|
}
|
|
|
|
print "\n";
|
|
|
|
$lineprefix = $oldprefix;
|
|
|
|
}
|
|
|
|
|
|
|
|
sub output_enum_rst(%) {
|
|
|
|
my %args = %{$_[0]};
|
|
|
|
my ($parameter);
|
2016-05-26 08:18:17 -06:00
|
|
|
my $oldprefix = $lineprefix;
|
2016-05-12 07:15:37 -06:00
|
|
|
my $count;
|
|
|
|
my $name = "enum " . $args{'enum'};
|
2016-05-12 07:15:38 -06:00
|
|
|
|
|
|
|
print "\n\n.. c:type:: " . $name . "\n\n";
|
2016-06-03 14:21:34 -06:00
|
|
|
print_lineno($declaration_start_line);
|
2016-05-26 08:18:17 -06:00
|
|
|
$lineprefix = " ";
|
|
|
|
output_highlight_rst($args{'purpose'});
|
|
|
|
print "\n";
|
2016-05-12 07:15:37 -06:00
|
|
|
|
2016-05-26 09:30:27 -06:00
|
|
|
print "**Constants**\n\n";
|
|
|
|
$lineprefix = " ";
|
2016-05-12 07:15:37 -06:00
|
|
|
foreach $parameter (@{$args{'parameterlist'}}) {
|
2016-05-26 09:30:27 -06:00
|
|
|
print "``$parameter``\n";
|
2016-05-12 07:15:37 -06:00
|
|
|
if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
|
|
|
|
output_highlight_rst($args{'parameterdescs'}{$parameter});
|
|
|
|
} else {
|
2016-05-27 15:48:17 -06:00
|
|
|
print " *undescribed*\n";
|
2016-05-12 07:15:37 -06:00
|
|
|
}
|
|
|
|
print "\n";
|
|
|
|
}
|
2016-05-26 08:18:17 -06:00
|
|
|
|
2016-05-12 07:15:37 -06:00
|
|
|
$lineprefix = $oldprefix;
|
|
|
|
output_section_rst(@_);
|
|
|
|
}
|
|
|
|
|
|
|
|
sub output_typedef_rst(%) {
|
|
|
|
my %args = %{$_[0]};
|
|
|
|
my ($parameter);
|
2016-05-26 08:18:17 -06:00
|
|
|
my $oldprefix = $lineprefix;
|
2016-05-12 07:15:37 -06:00
|
|
|
my $name = "typedef " . $args{'typedef'};
|
|
|
|
|
2016-05-12 07:15:38 -06:00
|
|
|
print "\n\n.. c:type:: " . $name . "\n\n";
|
2016-06-03 14:21:34 -06:00
|
|
|
print_lineno($declaration_start_line);
|
2016-05-26 08:18:17 -06:00
|
|
|
$lineprefix = " ";
|
|
|
|
output_highlight_rst($args{'purpose'});
|
|
|
|
print "\n";
|
2016-05-12 07:15:37 -06:00
|
|
|
|
2016-05-26 08:18:17 -06:00
|
|
|
$lineprefix = $oldprefix;
|
2016-05-12 07:15:37 -06:00
|
|
|
output_section_rst(@_);
|
|
|
|
}
|
|
|
|
|
|
|
|
sub output_struct_rst(%) {
|
|
|
|
my %args = %{$_[0]};
|
|
|
|
my ($parameter);
|
2016-05-26 08:18:17 -06:00
|
|
|
my $oldprefix = $lineprefix;
|
2016-05-12 07:15:37 -06:00
|
|
|
my $name = $args{'type'} . " " . $args{'struct'};
|
|
|
|
|
2016-05-12 07:15:38 -06:00
|
|
|
print "\n\n.. c:type:: " . $name . "\n\n";
|
2016-06-03 14:21:34 -06:00
|
|
|
print_lineno($declaration_start_line);
|
2016-05-26 08:18:17 -06:00
|
|
|
$lineprefix = " ";
|
|
|
|
output_highlight_rst($args{'purpose'});
|
|
|
|
print "\n";
|
2016-05-12 07:15:37 -06:00
|
|
|
|
2016-05-26 09:30:27 -06:00
|
|
|
print "**Definition**\n\n";
|
|
|
|
print "::\n\n";
|
scripts: kernel-doc: parse next structs/unions
There are several places within the Kernel tree with nested
structs/unions, like this one:
struct ingenic_cgu_clk_info {
const char *name;
enum {
CGU_CLK_NONE = 0,
CGU_CLK_EXT = BIT(0),
CGU_CLK_PLL = BIT(1),
CGU_CLK_GATE = BIT(2),
CGU_CLK_MUX = BIT(3),
CGU_CLK_MUX_GLITCHFREE = BIT(4),
CGU_CLK_DIV = BIT(5),
CGU_CLK_FIXDIV = BIT(6),
CGU_CLK_CUSTOM = BIT(7),
} type;
int parents[4];
union {
struct ingenic_cgu_pll_info pll;
struct {
struct ingenic_cgu_gate_info gate;
struct ingenic_cgu_mux_info mux;
struct ingenic_cgu_div_info div;
struct ingenic_cgu_fixdiv_info fixdiv;
};
struct ingenic_cgu_custom_info custom;
};
};
Currently, such struct is documented as:
**Definition**
::
struct ingenic_cgu_clk_info {
const char * name;
};
**Members**
``name``
name of the clock
With is obvioulsy wrong. It also generates an error:
drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum'
However, there's nothing wrong with this kernel-doc markup: everything
is documented there.
It makes sense to document all fields there. So, add a
way for the core to parse those structs.
With this patch, all documented fields will properly generate
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:13 -07:00
|
|
|
my $declaration = $args{'definition'};
|
|
|
|
$declaration =~ s/\t/ /g;
|
|
|
|
print " " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration };\n\n";
|
2016-05-12 07:15:37 -06:00
|
|
|
|
2016-05-26 09:30:27 -06:00
|
|
|
print "**Members**\n\n";
|
|
|
|
$lineprefix = " ";
|
2016-05-12 07:15:37 -06:00
|
|
|
foreach $parameter (@{$args{'parameterlist'}}) {
|
|
|
|
($parameter =~ /^#/) && next;
|
|
|
|
|
|
|
|
my $parameter_name = $parameter;
|
|
|
|
$parameter_name =~ s/\[.*//;
|
|
|
|
|
|
|
|
($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
|
|
|
|
$type = $args{'parametertypes'}{$parameter};
|
2016-06-03 14:21:34 -06:00
|
|
|
print_lineno($parameterdesc_start_lines{$parameter_name});
|
docs-rst: kernel-doc: better output struct members
Right now, for a struct, kernel-doc produces the following output:
.. c:type:: struct v4l2_prio_state
stores the priority states
**Definition**
::
struct v4l2_prio_state {
atomic_t prios[4];
};
**Members**
``atomic_t prios[4]``
array with elements to store the array priorities
Putting a member name in verbatim and adding a continuation line
causes the LaTeX output to generate something like:
item[atomic_t prios\[4\]] array with elements to store the array priorities
Everything inside "item" is non-breakable, with may produce
lines bigger than the column width.
Also, for function members, like:
int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num);
It puts the name of the member at the end, like:
int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) read
With is very confusing.
The best is to highlight what really matters: the member name.
is a secondary information.
So, change kernel-doc, for it to produce the output on a different way:
**Members**
``prios[4]``
array with elements to store the array priorities
Also, as the type is not part of LaTeX "item[]", LaTeX will split it into
multiple lines, if needed.
So, both LaTeX/PDF and HTML outputs will look good.
It should be noticed, however, that the way Sphinx LaTeX output handles
things like:
Foo
bar
is different than the HTML output. On HTML, it will produce something
like:
**Foo**
bar
While, on LaTeX, it puts both foo and bar at the same line, like:
**Foo** bar
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-22 19:02:57 -06:00
|
|
|
print "``" . $parameter . "``\n";
|
2016-05-12 07:15:37 -06:00
|
|
|
output_highlight_rst($args{'parameterdescs'}{$parameter_name});
|
|
|
|
print "\n";
|
|
|
|
}
|
|
|
|
print "\n";
|
2016-05-26 08:18:17 -06:00
|
|
|
|
|
|
|
$lineprefix = $oldprefix;
|
2016-05-12 07:15:37 -06:00
|
|
|
output_section_rst(@_);
|
|
|
|
}
|
|
|
|
|
2017-11-20 11:40:40 -07:00
|
|
|
## none mode output functions
|
|
|
|
|
|
|
|
sub output_function_none(%) {
|
|
|
|
}
|
|
|
|
|
|
|
|
sub output_enum_none(%) {
|
|
|
|
}
|
|
|
|
|
|
|
|
sub output_typedef_none(%) {
|
|
|
|
}
|
|
|
|
|
|
|
|
sub output_struct_none(%) {
|
|
|
|
}
|
|
|
|
|
|
|
|
sub output_blockhead_none(%) {
|
|
|
|
}
|
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
##
|
2006-10-11 02:22:12 -06:00
|
|
|
# generic output function for all types (function, struct/union, typedef, enum);
|
|
|
|
# calls the generated, variable output_ function name based on
|
|
|
|
# functype and output_mode
|
2005-04-16 16:20:36 -06:00
|
|
|
sub output_declaration {
|
|
|
|
no strict 'refs';
|
|
|
|
my $name = shift;
|
|
|
|
my $functype = shift;
|
|
|
|
my $func = "output_${functype}_$output_mode";
|
2016-05-29 13:19:35 -06:00
|
|
|
if (($output_selection == OUTPUT_ALL) ||
|
|
|
|
(($output_selection == OUTPUT_INCLUDE ||
|
|
|
|
$output_selection == OUTPUT_EXPORTED) &&
|
|
|
|
defined($function_table{$name})) ||
|
|
|
|
(($output_selection == OUTPUT_EXCLUDE ||
|
|
|
|
$output_selection == OUTPUT_INTERNAL) &&
|
|
|
|
!($functype eq "function" && defined($function_table{$name}))))
|
2005-04-16 16:20:36 -06:00
|
|
|
{
|
2007-05-08 01:24:39 -06:00
|
|
|
&$func(@_);
|
2005-04-16 16:20:36 -06:00
|
|
|
$section_counter++;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
##
|
2006-10-11 02:22:12 -06:00
|
|
|
# generic output function - calls the right one based on current output mode.
|
2007-10-24 16:08:48 -06:00
|
|
|
sub output_blockhead {
|
2005-04-16 16:20:36 -06:00
|
|
|
no strict 'refs';
|
2009-06-09 09:50:38 -06:00
|
|
|
my $func = "output_blockhead_" . $output_mode;
|
2005-04-16 16:20:36 -06:00
|
|
|
&$func(@_);
|
|
|
|
$section_counter++;
|
|
|
|
}
|
|
|
|
|
|
|
|
##
|
2006-02-01 04:06:58 -07:00
|
|
|
# takes a declaration (struct, union, enum, typedef) and
|
2005-04-16 16:20:36 -06:00
|
|
|
# invokes the right handler. NOT called for functions.
|
|
|
|
sub dump_declaration($$) {
|
|
|
|
no strict 'refs';
|
|
|
|
my ($prototype, $file) = @_;
|
2009-06-09 09:50:38 -06:00
|
|
|
my $func = "dump_" . $decl_type;
|
2005-04-16 16:20:36 -06:00
|
|
|
&$func(@_);
|
|
|
|
}
|
|
|
|
|
|
|
|
sub dump_union($$) {
|
|
|
|
dump_struct(@_);
|
|
|
|
}
|
|
|
|
|
|
|
|
sub dump_struct($$) {
|
|
|
|
my $x = shift;
|
|
|
|
my $file = shift;
|
|
|
|
|
2009-04-30 16:08:53 -06:00
|
|
|
if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
|
2017-09-19 05:08:13 -06:00
|
|
|
my $decl_type = $1;
|
2007-05-08 01:24:39 -06:00
|
|
|
$declaration_name = $2;
|
|
|
|
my $members = $3;
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2005-11-13 17:08:13 -07:00
|
|
|
# ignore members marked private:
|
2015-10-05 06:03:48 -06:00
|
|
|
$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
|
|
|
|
$members =~ s/\/\*\s*private:.*//gosi;
|
2005-11-13 17:08:13 -07:00
|
|
|
# strip comments:
|
|
|
|
$members =~ s/\/\*.*?\*\///gos;
|
2010-03-23 14:35:14 -06:00
|
|
|
# strip attributes
|
2015-08-23 13:35:23 -06:00
|
|
|
$members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
|
2014-12-10 16:41:28 -07:00
|
|
|
$members =~ s/__aligned\s*\([^;]*\)//gos;
|
2015-08-23 13:35:23 -06:00
|
|
|
$members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
|
2015-11-08 02:52:00 -07:00
|
|
|
# replace DECLARE_BITMAP
|
2017-12-08 07:05:12 -07:00
|
|
|
$members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
|
2017-06-30 20:09:59 -06:00
|
|
|
# replace DECLARE_HASHTABLE
|
2017-12-08 07:05:12 -07:00
|
|
|
$members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
|
|
|
|
# replace DECLARE_KFIFO
|
|
|
|
$members =~ s/DECLARE_KFIFO\s*\(([^,)]+),\s*([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
|
|
|
|
# replace DECLARE_KFIFO_PTR
|
|
|
|
$members =~ s/DECLARE_KFIFO_PTR\s*\(([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
|
2005-11-13 17:08:13 -07:00
|
|
|
|
scripts: kernel-doc: parse next structs/unions
There are several places within the Kernel tree with nested
structs/unions, like this one:
struct ingenic_cgu_clk_info {
const char *name;
enum {
CGU_CLK_NONE = 0,
CGU_CLK_EXT = BIT(0),
CGU_CLK_PLL = BIT(1),
CGU_CLK_GATE = BIT(2),
CGU_CLK_MUX = BIT(3),
CGU_CLK_MUX_GLITCHFREE = BIT(4),
CGU_CLK_DIV = BIT(5),
CGU_CLK_FIXDIV = BIT(6),
CGU_CLK_CUSTOM = BIT(7),
} type;
int parents[4];
union {
struct ingenic_cgu_pll_info pll;
struct {
struct ingenic_cgu_gate_info gate;
struct ingenic_cgu_mux_info mux;
struct ingenic_cgu_div_info div;
struct ingenic_cgu_fixdiv_info fixdiv;
};
struct ingenic_cgu_custom_info custom;
};
};
Currently, such struct is documented as:
**Definition**
::
struct ingenic_cgu_clk_info {
const char * name;
};
**Members**
``name``
name of the clock
With is obvioulsy wrong. It also generates an error:
drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum'
However, there's nothing wrong with this kernel-doc markup: everything
is documented there.
It makes sense to document all fields there. So, add a
way for the core to parse those structs.
With this patch, all documented fields will properly generate
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:13 -07:00
|
|
|
my $declaration = $members;
|
|
|
|
|
|
|
|
# Split nested struct/union elements as newer ones
|
scripts: kernel-doc: improve nested logic to handle multiple identifiers
It is possible to use nested structs like:
struct {
struct {
void *arg1;
} st1, st2, *st3, st4;
};
Handling it requires to split each parameter. Change the logic
to allow such definitions.
In order to test the new nested logic, the following file
was used to test
<code>
struct foo { int a; }; /* Just to avoid errors if compiled */
/**
* struct my_struct - a struct with nested unions and structs
* @arg1: first argument of anonymous union/anonymous struct
* @arg2: second argument of anonymous union/anonymous struct
* @arg1b: first argument of anonymous union/anonymous struct
* @arg2b: second argument of anonymous union/anonymous struct
* @arg3: third argument of anonymous union/anonymous struct
* @arg4: fourth argument of anonymous union/anonymous struct
* @bar.st1.arg1: first argument of struct st1 on union bar
* @bar.st1.arg2: second argument of struct st1 on union bar
* @bar.st1.bar1: bar1 at st1
* @bar.st1.bar2: bar2 at st1
* @bar.st2.arg1: first argument of struct st2 on union bar
* @bar.st2.arg2: second argument of struct st2 on union bar
* @bar.st3.arg2: second argument of struct st3 on union bar
* @f1: nested function on anonimous union/struct
* @bar.st2.f2: nested function on named union/struct
*/
struct my_struct {
/* Anonymous union/struct*/
union {
struct {
char arg1 : 1;
char arg2 : 3;
};
struct {
int arg1b;
int arg2b;
};
struct {
void *arg3;
int arg4;
int (*f1)(char foo, int bar);
};
};
union {
struct {
int arg1;
int arg2;
struct foo bar1, *bar2;
} st1; /* bar.st1 is undocumented, cause a warning */
struct {
void *arg1; /* bar.st3.arg1 is undocumented, cause a warning */
int arg2;
int (*f2)(char foo, int bar); /* bar.st3.fn2 is undocumented, cause a warning */
} st2, st3, *st4;
int (*f3)(char foo, int bar); /* f3 is undocumented, cause a warning */
} bar; /* bar is undocumented, cause a warning */
/* private: */
int undoc_privat; /* is undocumented but private, no warning */
/* public: */
int undoc_public; /* is undocumented, cause a warning */
};
</code>
It produces the following warnings, as expected:
test2.h:57: warning: Function parameter or member 'bar' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.f3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'undoc_public' not described in 'my_struct'
Suggested-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:17 -07:00
|
|
|
while ($members =~ m/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/) {
|
|
|
|
my $newmember;
|
|
|
|
my $maintype = $1;
|
|
|
|
my $ids = $4;
|
|
|
|
my $content = $3;
|
|
|
|
foreach my $id(split /,/, $ids) {
|
|
|
|
$newmember .= "$maintype $id; ";
|
|
|
|
|
scripts: kernel-doc: parse next structs/unions
There are several places within the Kernel tree with nested
structs/unions, like this one:
struct ingenic_cgu_clk_info {
const char *name;
enum {
CGU_CLK_NONE = 0,
CGU_CLK_EXT = BIT(0),
CGU_CLK_PLL = BIT(1),
CGU_CLK_GATE = BIT(2),
CGU_CLK_MUX = BIT(3),
CGU_CLK_MUX_GLITCHFREE = BIT(4),
CGU_CLK_DIV = BIT(5),
CGU_CLK_FIXDIV = BIT(6),
CGU_CLK_CUSTOM = BIT(7),
} type;
int parents[4];
union {
struct ingenic_cgu_pll_info pll;
struct {
struct ingenic_cgu_gate_info gate;
struct ingenic_cgu_mux_info mux;
struct ingenic_cgu_div_info div;
struct ingenic_cgu_fixdiv_info fixdiv;
};
struct ingenic_cgu_custom_info custom;
};
};
Currently, such struct is documented as:
**Definition**
::
struct ingenic_cgu_clk_info {
const char * name;
};
**Members**
``name``
name of the clock
With is obvioulsy wrong. It also generates an error:
drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum'
However, there's nothing wrong with this kernel-doc markup: everything
is documented there.
It makes sense to document all fields there. So, add a
way for the core to parse those structs.
With this patch, all documented fields will properly generate
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:13 -07:00
|
|
|
$id =~ s/[:\[].*//;
|
scripts: kernel-doc: improve nested logic to handle multiple identifiers
It is possible to use nested structs like:
struct {
struct {
void *arg1;
} st1, st2, *st3, st4;
};
Handling it requires to split each parameter. Change the logic
to allow such definitions.
In order to test the new nested logic, the following file
was used to test
<code>
struct foo { int a; }; /* Just to avoid errors if compiled */
/**
* struct my_struct - a struct with nested unions and structs
* @arg1: first argument of anonymous union/anonymous struct
* @arg2: second argument of anonymous union/anonymous struct
* @arg1b: first argument of anonymous union/anonymous struct
* @arg2b: second argument of anonymous union/anonymous struct
* @arg3: third argument of anonymous union/anonymous struct
* @arg4: fourth argument of anonymous union/anonymous struct
* @bar.st1.arg1: first argument of struct st1 on union bar
* @bar.st1.arg2: second argument of struct st1 on union bar
* @bar.st1.bar1: bar1 at st1
* @bar.st1.bar2: bar2 at st1
* @bar.st2.arg1: first argument of struct st2 on union bar
* @bar.st2.arg2: second argument of struct st2 on union bar
* @bar.st3.arg2: second argument of struct st3 on union bar
* @f1: nested function on anonimous union/struct
* @bar.st2.f2: nested function on named union/struct
*/
struct my_struct {
/* Anonymous union/struct*/
union {
struct {
char arg1 : 1;
char arg2 : 3;
};
struct {
int arg1b;
int arg2b;
};
struct {
void *arg3;
int arg4;
int (*f1)(char foo, int bar);
};
};
union {
struct {
int arg1;
int arg2;
struct foo bar1, *bar2;
} st1; /* bar.st1 is undocumented, cause a warning */
struct {
void *arg1; /* bar.st3.arg1 is undocumented, cause a warning */
int arg2;
int (*f2)(char foo, int bar); /* bar.st3.fn2 is undocumented, cause a warning */
} st2, st3, *st4;
int (*f3)(char foo, int bar); /* f3 is undocumented, cause a warning */
} bar; /* bar is undocumented, cause a warning */
/* private: */
int undoc_privat; /* is undocumented but private, no warning */
/* public: */
int undoc_public; /* is undocumented, cause a warning */
};
</code>
It produces the following warnings, as expected:
test2.h:57: warning: Function parameter or member 'bar' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.f3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'undoc_public' not described in 'my_struct'
Suggested-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:17 -07:00
|
|
|
$id =~ s/^\s*\**(\S+)\s*/$1/;
|
scripts: kernel-doc: parse next structs/unions
There are several places within the Kernel tree with nested
structs/unions, like this one:
struct ingenic_cgu_clk_info {
const char *name;
enum {
CGU_CLK_NONE = 0,
CGU_CLK_EXT = BIT(0),
CGU_CLK_PLL = BIT(1),
CGU_CLK_GATE = BIT(2),
CGU_CLK_MUX = BIT(3),
CGU_CLK_MUX_GLITCHFREE = BIT(4),
CGU_CLK_DIV = BIT(5),
CGU_CLK_FIXDIV = BIT(6),
CGU_CLK_CUSTOM = BIT(7),
} type;
int parents[4];
union {
struct ingenic_cgu_pll_info pll;
struct {
struct ingenic_cgu_gate_info gate;
struct ingenic_cgu_mux_info mux;
struct ingenic_cgu_div_info div;
struct ingenic_cgu_fixdiv_info fixdiv;
};
struct ingenic_cgu_custom_info custom;
};
};
Currently, such struct is documented as:
**Definition**
::
struct ingenic_cgu_clk_info {
const char * name;
};
**Members**
``name``
name of the clock
With is obvioulsy wrong. It also generates an error:
drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum'
However, there's nothing wrong with this kernel-doc markup: everything
is documented there.
It makes sense to document all fields there. So, add a
way for the core to parse those structs.
With this patch, all documented fields will properly generate
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:13 -07:00
|
|
|
foreach my $arg (split /;/, $content) {
|
|
|
|
next if ($arg =~ m/^\s*$/);
|
2017-12-18 05:30:16 -07:00
|
|
|
if ($arg =~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) {
|
|
|
|
# pointer-to-function
|
|
|
|
my $type = $1;
|
|
|
|
my $name = $2;
|
|
|
|
my $extra = $3;
|
|
|
|
next if (!$name);
|
|
|
|
if ($id =~ m/^\s*$/) {
|
|
|
|
# anonymous struct/union
|
scripts: kernel-doc: improve nested logic to handle multiple identifiers
It is possible to use nested structs like:
struct {
struct {
void *arg1;
} st1, st2, *st3, st4;
};
Handling it requires to split each parameter. Change the logic
to allow such definitions.
In order to test the new nested logic, the following file
was used to test
<code>
struct foo { int a; }; /* Just to avoid errors if compiled */
/**
* struct my_struct - a struct with nested unions and structs
* @arg1: first argument of anonymous union/anonymous struct
* @arg2: second argument of anonymous union/anonymous struct
* @arg1b: first argument of anonymous union/anonymous struct
* @arg2b: second argument of anonymous union/anonymous struct
* @arg3: third argument of anonymous union/anonymous struct
* @arg4: fourth argument of anonymous union/anonymous struct
* @bar.st1.arg1: first argument of struct st1 on union bar
* @bar.st1.arg2: second argument of struct st1 on union bar
* @bar.st1.bar1: bar1 at st1
* @bar.st1.bar2: bar2 at st1
* @bar.st2.arg1: first argument of struct st2 on union bar
* @bar.st2.arg2: second argument of struct st2 on union bar
* @bar.st3.arg2: second argument of struct st3 on union bar
* @f1: nested function on anonimous union/struct
* @bar.st2.f2: nested function on named union/struct
*/
struct my_struct {
/* Anonymous union/struct*/
union {
struct {
char arg1 : 1;
char arg2 : 3;
};
struct {
int arg1b;
int arg2b;
};
struct {
void *arg3;
int arg4;
int (*f1)(char foo, int bar);
};
};
union {
struct {
int arg1;
int arg2;
struct foo bar1, *bar2;
} st1; /* bar.st1 is undocumented, cause a warning */
struct {
void *arg1; /* bar.st3.arg1 is undocumented, cause a warning */
int arg2;
int (*f2)(char foo, int bar); /* bar.st3.fn2 is undocumented, cause a warning */
} st2, st3, *st4;
int (*f3)(char foo, int bar); /* f3 is undocumented, cause a warning */
} bar; /* bar is undocumented, cause a warning */
/* private: */
int undoc_privat; /* is undocumented but private, no warning */
/* public: */
int undoc_public; /* is undocumented, cause a warning */
};
</code>
It produces the following warnings, as expected:
test2.h:57: warning: Function parameter or member 'bar' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.f3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'undoc_public' not described in 'my_struct'
Suggested-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:17 -07:00
|
|
|
$newmember .= "$type$name$extra; ";
|
2017-12-18 05:30:16 -07:00
|
|
|
} else {
|
scripts: kernel-doc: improve nested logic to handle multiple identifiers
It is possible to use nested structs like:
struct {
struct {
void *arg1;
} st1, st2, *st3, st4;
};
Handling it requires to split each parameter. Change the logic
to allow such definitions.
In order to test the new nested logic, the following file
was used to test
<code>
struct foo { int a; }; /* Just to avoid errors if compiled */
/**
* struct my_struct - a struct with nested unions and structs
* @arg1: first argument of anonymous union/anonymous struct
* @arg2: second argument of anonymous union/anonymous struct
* @arg1b: first argument of anonymous union/anonymous struct
* @arg2b: second argument of anonymous union/anonymous struct
* @arg3: third argument of anonymous union/anonymous struct
* @arg4: fourth argument of anonymous union/anonymous struct
* @bar.st1.arg1: first argument of struct st1 on union bar
* @bar.st1.arg2: second argument of struct st1 on union bar
* @bar.st1.bar1: bar1 at st1
* @bar.st1.bar2: bar2 at st1
* @bar.st2.arg1: first argument of struct st2 on union bar
* @bar.st2.arg2: second argument of struct st2 on union bar
* @bar.st3.arg2: second argument of struct st3 on union bar
* @f1: nested function on anonimous union/struct
* @bar.st2.f2: nested function on named union/struct
*/
struct my_struct {
/* Anonymous union/struct*/
union {
struct {
char arg1 : 1;
char arg2 : 3;
};
struct {
int arg1b;
int arg2b;
};
struct {
void *arg3;
int arg4;
int (*f1)(char foo, int bar);
};
};
union {
struct {
int arg1;
int arg2;
struct foo bar1, *bar2;
} st1; /* bar.st1 is undocumented, cause a warning */
struct {
void *arg1; /* bar.st3.arg1 is undocumented, cause a warning */
int arg2;
int (*f2)(char foo, int bar); /* bar.st3.fn2 is undocumented, cause a warning */
} st2, st3, *st4;
int (*f3)(char foo, int bar); /* f3 is undocumented, cause a warning */
} bar; /* bar is undocumented, cause a warning */
/* private: */
int undoc_privat; /* is undocumented but private, no warning */
/* public: */
int undoc_public; /* is undocumented, cause a warning */
};
</code>
It produces the following warnings, as expected:
test2.h:57: warning: Function parameter or member 'bar' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.f3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'undoc_public' not described in 'my_struct'
Suggested-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:17 -07:00
|
|
|
$newmember .= "$type$id.$name$extra; ";
|
2017-12-18 05:30:16 -07:00
|
|
|
}
|
scripts: kernel-doc: parse next structs/unions
There are several places within the Kernel tree with nested
structs/unions, like this one:
struct ingenic_cgu_clk_info {
const char *name;
enum {
CGU_CLK_NONE = 0,
CGU_CLK_EXT = BIT(0),
CGU_CLK_PLL = BIT(1),
CGU_CLK_GATE = BIT(2),
CGU_CLK_MUX = BIT(3),
CGU_CLK_MUX_GLITCHFREE = BIT(4),
CGU_CLK_DIV = BIT(5),
CGU_CLK_FIXDIV = BIT(6),
CGU_CLK_CUSTOM = BIT(7),
} type;
int parents[4];
union {
struct ingenic_cgu_pll_info pll;
struct {
struct ingenic_cgu_gate_info gate;
struct ingenic_cgu_mux_info mux;
struct ingenic_cgu_div_info div;
struct ingenic_cgu_fixdiv_info fixdiv;
};
struct ingenic_cgu_custom_info custom;
};
};
Currently, such struct is documented as:
**Definition**
::
struct ingenic_cgu_clk_info {
const char * name;
};
**Members**
``name``
name of the clock
With is obvioulsy wrong. It also generates an error:
drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum'
However, there's nothing wrong with this kernel-doc markup: everything
is documented there.
It makes sense to document all fields there. So, add a
way for the core to parse those structs.
With this patch, all documented fields will properly generate
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:13 -07:00
|
|
|
} else {
|
scripts: kernel-doc: improve nested logic to handle multiple identifiers
It is possible to use nested structs like:
struct {
struct {
void *arg1;
} st1, st2, *st3, st4;
};
Handling it requires to split each parameter. Change the logic
to allow such definitions.
In order to test the new nested logic, the following file
was used to test
<code>
struct foo { int a; }; /* Just to avoid errors if compiled */
/**
* struct my_struct - a struct with nested unions and structs
* @arg1: first argument of anonymous union/anonymous struct
* @arg2: second argument of anonymous union/anonymous struct
* @arg1b: first argument of anonymous union/anonymous struct
* @arg2b: second argument of anonymous union/anonymous struct
* @arg3: third argument of anonymous union/anonymous struct
* @arg4: fourth argument of anonymous union/anonymous struct
* @bar.st1.arg1: first argument of struct st1 on union bar
* @bar.st1.arg2: second argument of struct st1 on union bar
* @bar.st1.bar1: bar1 at st1
* @bar.st1.bar2: bar2 at st1
* @bar.st2.arg1: first argument of struct st2 on union bar
* @bar.st2.arg2: second argument of struct st2 on union bar
* @bar.st3.arg2: second argument of struct st3 on union bar
* @f1: nested function on anonimous union/struct
* @bar.st2.f2: nested function on named union/struct
*/
struct my_struct {
/* Anonymous union/struct*/
union {
struct {
char arg1 : 1;
char arg2 : 3;
};
struct {
int arg1b;
int arg2b;
};
struct {
void *arg3;
int arg4;
int (*f1)(char foo, int bar);
};
};
union {
struct {
int arg1;
int arg2;
struct foo bar1, *bar2;
} st1; /* bar.st1 is undocumented, cause a warning */
struct {
void *arg1; /* bar.st3.arg1 is undocumented, cause a warning */
int arg2;
int (*f2)(char foo, int bar); /* bar.st3.fn2 is undocumented, cause a warning */
} st2, st3, *st4;
int (*f3)(char foo, int bar); /* f3 is undocumented, cause a warning */
} bar; /* bar is undocumented, cause a warning */
/* private: */
int undoc_privat; /* is undocumented but private, no warning */
/* public: */
int undoc_public; /* is undocumented, cause a warning */
};
</code>
It produces the following warnings, as expected:
test2.h:57: warning: Function parameter or member 'bar' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.f3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'undoc_public' not described in 'my_struct'
Suggested-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:17 -07:00
|
|
|
my $type;
|
|
|
|
my $names;
|
|
|
|
$arg =~ s/^\s+//;
|
|
|
|
$arg =~ s/\s+$//;
|
|
|
|
# Handle bitmaps
|
|
|
|
$arg =~ s/:\s*\d+\s*//g;
|
|
|
|
# Handle arrays
|
|
|
|
$arg =~ s/\[\S+\]//g;
|
|
|
|
# The type may have multiple words,
|
|
|
|
# and multiple IDs can be defined, like:
|
|
|
|
# const struct foo, *bar, foobar
|
|
|
|
# So, we remove spaces when parsing the
|
|
|
|
# names, in order to match just names
|
|
|
|
# and commas for the names
|
|
|
|
$arg =~ s/\s*,\s*/,/g;
|
|
|
|
if ($arg =~ m/(.*)\s+([\S+,]+)/) {
|
|
|
|
$type = $1;
|
|
|
|
$names = $2;
|
2017-12-18 05:30:16 -07:00
|
|
|
} else {
|
scripts: kernel-doc: improve nested logic to handle multiple identifiers
It is possible to use nested structs like:
struct {
struct {
void *arg1;
} st1, st2, *st3, st4;
};
Handling it requires to split each parameter. Change the logic
to allow such definitions.
In order to test the new nested logic, the following file
was used to test
<code>
struct foo { int a; }; /* Just to avoid errors if compiled */
/**
* struct my_struct - a struct with nested unions and structs
* @arg1: first argument of anonymous union/anonymous struct
* @arg2: second argument of anonymous union/anonymous struct
* @arg1b: first argument of anonymous union/anonymous struct
* @arg2b: second argument of anonymous union/anonymous struct
* @arg3: third argument of anonymous union/anonymous struct
* @arg4: fourth argument of anonymous union/anonymous struct
* @bar.st1.arg1: first argument of struct st1 on union bar
* @bar.st1.arg2: second argument of struct st1 on union bar
* @bar.st1.bar1: bar1 at st1
* @bar.st1.bar2: bar2 at st1
* @bar.st2.arg1: first argument of struct st2 on union bar
* @bar.st2.arg2: second argument of struct st2 on union bar
* @bar.st3.arg2: second argument of struct st3 on union bar
* @f1: nested function on anonimous union/struct
* @bar.st2.f2: nested function on named union/struct
*/
struct my_struct {
/* Anonymous union/struct*/
union {
struct {
char arg1 : 1;
char arg2 : 3;
};
struct {
int arg1b;
int arg2b;
};
struct {
void *arg3;
int arg4;
int (*f1)(char foo, int bar);
};
};
union {
struct {
int arg1;
int arg2;
struct foo bar1, *bar2;
} st1; /* bar.st1 is undocumented, cause a warning */
struct {
void *arg1; /* bar.st3.arg1 is undocumented, cause a warning */
int arg2;
int (*f2)(char foo, int bar); /* bar.st3.fn2 is undocumented, cause a warning */
} st2, st3, *st4;
int (*f3)(char foo, int bar); /* f3 is undocumented, cause a warning */
} bar; /* bar is undocumented, cause a warning */
/* private: */
int undoc_privat; /* is undocumented but private, no warning */
/* public: */
int undoc_public; /* is undocumented, cause a warning */
};
</code>
It produces the following warnings, as expected:
test2.h:57: warning: Function parameter or member 'bar' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.f3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'undoc_public' not described in 'my_struct'
Suggested-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:17 -07:00
|
|
|
$newmember .= "$arg; ";
|
|
|
|
next;
|
|
|
|
}
|
|
|
|
foreach my $name (split /,/, $names) {
|
|
|
|
$name =~ s/^\s*\**(\S+)\s*/$1/;
|
|
|
|
next if (($name =~ m/^\s*$/));
|
|
|
|
if ($id =~ m/^\s*$/) {
|
|
|
|
# anonymous struct/union
|
|
|
|
$newmember .= "$type $name; ";
|
|
|
|
} else {
|
|
|
|
$newmember .= "$type $id.$name; ";
|
|
|
|
}
|
2017-12-18 05:30:16 -07:00
|
|
|
}
|
scripts: kernel-doc: parse next structs/unions
There are several places within the Kernel tree with nested
structs/unions, like this one:
struct ingenic_cgu_clk_info {
const char *name;
enum {
CGU_CLK_NONE = 0,
CGU_CLK_EXT = BIT(0),
CGU_CLK_PLL = BIT(1),
CGU_CLK_GATE = BIT(2),
CGU_CLK_MUX = BIT(3),
CGU_CLK_MUX_GLITCHFREE = BIT(4),
CGU_CLK_DIV = BIT(5),
CGU_CLK_FIXDIV = BIT(6),
CGU_CLK_CUSTOM = BIT(7),
} type;
int parents[4];
union {
struct ingenic_cgu_pll_info pll;
struct {
struct ingenic_cgu_gate_info gate;
struct ingenic_cgu_mux_info mux;
struct ingenic_cgu_div_info div;
struct ingenic_cgu_fixdiv_info fixdiv;
};
struct ingenic_cgu_custom_info custom;
};
};
Currently, such struct is documented as:
**Definition**
::
struct ingenic_cgu_clk_info {
const char * name;
};
**Members**
``name``
name of the clock
With is obvioulsy wrong. It also generates an error:
drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum'
However, there's nothing wrong with this kernel-doc markup: everything
is documented there.
It makes sense to document all fields there. So, add a
way for the core to parse those structs.
With this patch, all documented fields will properly generate
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:13 -07:00
|
|
|
}
|
|
|
|
}
|
scripts: kernel-doc: improve nested logic to handle multiple identifiers
It is possible to use nested structs like:
struct {
struct {
void *arg1;
} st1, st2, *st3, st4;
};
Handling it requires to split each parameter. Change the logic
to allow such definitions.
In order to test the new nested logic, the following file
was used to test
<code>
struct foo { int a; }; /* Just to avoid errors if compiled */
/**
* struct my_struct - a struct with nested unions and structs
* @arg1: first argument of anonymous union/anonymous struct
* @arg2: second argument of anonymous union/anonymous struct
* @arg1b: first argument of anonymous union/anonymous struct
* @arg2b: second argument of anonymous union/anonymous struct
* @arg3: third argument of anonymous union/anonymous struct
* @arg4: fourth argument of anonymous union/anonymous struct
* @bar.st1.arg1: first argument of struct st1 on union bar
* @bar.st1.arg2: second argument of struct st1 on union bar
* @bar.st1.bar1: bar1 at st1
* @bar.st1.bar2: bar2 at st1
* @bar.st2.arg1: first argument of struct st2 on union bar
* @bar.st2.arg2: second argument of struct st2 on union bar
* @bar.st3.arg2: second argument of struct st3 on union bar
* @f1: nested function on anonimous union/struct
* @bar.st2.f2: nested function on named union/struct
*/
struct my_struct {
/* Anonymous union/struct*/
union {
struct {
char arg1 : 1;
char arg2 : 3;
};
struct {
int arg1b;
int arg2b;
};
struct {
void *arg3;
int arg4;
int (*f1)(char foo, int bar);
};
};
union {
struct {
int arg1;
int arg2;
struct foo bar1, *bar2;
} st1; /* bar.st1 is undocumented, cause a warning */
struct {
void *arg1; /* bar.st3.arg1 is undocumented, cause a warning */
int arg2;
int (*f2)(char foo, int bar); /* bar.st3.fn2 is undocumented, cause a warning */
} st2, st3, *st4;
int (*f3)(char foo, int bar); /* f3 is undocumented, cause a warning */
} bar; /* bar is undocumented, cause a warning */
/* private: */
int undoc_privat; /* is undocumented but private, no warning */
/* public: */
int undoc_public; /* is undocumented, cause a warning */
};
</code>
It produces the following warnings, as expected:
test2.h:57: warning: Function parameter or member 'bar' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.f3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'undoc_public' not described in 'my_struct'
Suggested-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:17 -07:00
|
|
|
}
|
|
|
|
$members =~ s/(struct|union)([^\{\};]+)\{([^\{\}]*)}([^\{\}\;]*)\;/$newmember/;
|
|
|
|
}
|
scripts: kernel-doc: parse next structs/unions
There are several places within the Kernel tree with nested
structs/unions, like this one:
struct ingenic_cgu_clk_info {
const char *name;
enum {
CGU_CLK_NONE = 0,
CGU_CLK_EXT = BIT(0),
CGU_CLK_PLL = BIT(1),
CGU_CLK_GATE = BIT(2),
CGU_CLK_MUX = BIT(3),
CGU_CLK_MUX_GLITCHFREE = BIT(4),
CGU_CLK_DIV = BIT(5),
CGU_CLK_FIXDIV = BIT(6),
CGU_CLK_CUSTOM = BIT(7),
} type;
int parents[4];
union {
struct ingenic_cgu_pll_info pll;
struct {
struct ingenic_cgu_gate_info gate;
struct ingenic_cgu_mux_info mux;
struct ingenic_cgu_div_info div;
struct ingenic_cgu_fixdiv_info fixdiv;
};
struct ingenic_cgu_custom_info custom;
};
};
Currently, such struct is documented as:
**Definition**
::
struct ingenic_cgu_clk_info {
const char * name;
};
**Members**
``name``
name of the clock
With is obvioulsy wrong. It also generates an error:
drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum'
However, there's nothing wrong with this kernel-doc markup: everything
is documented there.
It makes sense to document all fields there. So, add a
way for the core to parse those structs.
With this patch, all documented fields will properly generate
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:13 -07:00
|
|
|
|
|
|
|
# Ignore other nested elements, like enums
|
|
|
|
$members =~ s/({[^\{\}]*})//g;
|
|
|
|
|
scripts: kernel-doc: print the declaration name on warnings
The logic at create_parameterlist()'s ancillary push_parameter()
function has already a way to output the declaration name, with
would help to discover what declaration is missing.
However, currently, the logic is utterly broken, as it uses
the var $type with a wrong meaning. With the current code,
it will never print anything. I suspect that originally
it was using the second argument of output_declaration().
I opted to not rely on a globally defined $declaration_name,
but, instead, to pass it explicitly as a parameter.
While here, I removed a unaligned check for !$anon_struct_union.
This is not needed, as, if $anon_struct_union is not zero,
$parameterdescs{$param} will be defined.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:15 -07:00
|
|
|
create_parameterlist($members, ';', $file, $declaration_name);
|
2017-12-18 05:30:14 -07:00
|
|
|
check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual);
|
2005-04-16 16:20:36 -06:00
|
|
|
|
scripts: kernel-doc: parse next structs/unions
There are several places within the Kernel tree with nested
structs/unions, like this one:
struct ingenic_cgu_clk_info {
const char *name;
enum {
CGU_CLK_NONE = 0,
CGU_CLK_EXT = BIT(0),
CGU_CLK_PLL = BIT(1),
CGU_CLK_GATE = BIT(2),
CGU_CLK_MUX = BIT(3),
CGU_CLK_MUX_GLITCHFREE = BIT(4),
CGU_CLK_DIV = BIT(5),
CGU_CLK_FIXDIV = BIT(6),
CGU_CLK_CUSTOM = BIT(7),
} type;
int parents[4];
union {
struct ingenic_cgu_pll_info pll;
struct {
struct ingenic_cgu_gate_info gate;
struct ingenic_cgu_mux_info mux;
struct ingenic_cgu_div_info div;
struct ingenic_cgu_fixdiv_info fixdiv;
};
struct ingenic_cgu_custom_info custom;
};
};
Currently, such struct is documented as:
**Definition**
::
struct ingenic_cgu_clk_info {
const char * name;
};
**Members**
``name``
name of the clock
With is obvioulsy wrong. It also generates an error:
drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum'
However, there's nothing wrong with this kernel-doc markup: everything
is documented there.
It makes sense to document all fields there. So, add a
way for the core to parse those structs.
With this patch, all documented fields will properly generate
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:13 -07:00
|
|
|
# Adjust declaration for better display
|
|
|
|
$declaration =~ s/([{;])/$1\n/g;
|
|
|
|
$declaration =~ s/}\s+;/};/g;
|
|
|
|
# Better handle inlined enums
|
|
|
|
do {} while ($declaration =~ s/(enum\s+{[^}]+),([^\n])/$1,\n$2/);
|
|
|
|
|
|
|
|
my @def_args = split /\n/, $declaration;
|
|
|
|
my $level = 1;
|
|
|
|
$declaration = "";
|
|
|
|
foreach my $clause (@def_args) {
|
|
|
|
$clause =~ s/^\s+//;
|
|
|
|
$clause =~ s/\s+$//;
|
|
|
|
$clause =~ s/\s+/ /;
|
|
|
|
next if (!$clause);
|
|
|
|
$level-- if ($clause =~ m/(})/ && $level > 1);
|
|
|
|
if (!($clause =~ m/^\s*#/)) {
|
|
|
|
$declaration .= "\t" x $level;
|
|
|
|
}
|
|
|
|
$declaration .= "\t" . $clause . "\n";
|
|
|
|
$level++ if ($clause =~ m/({)/ && !($clause =~m/}/));
|
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
output_declaration($declaration_name,
|
|
|
|
'struct',
|
|
|
|
{'struct' => $declaration_name,
|
|
|
|
'module' => $modulename,
|
scripts: kernel-doc: parse next structs/unions
There are several places within the Kernel tree with nested
structs/unions, like this one:
struct ingenic_cgu_clk_info {
const char *name;
enum {
CGU_CLK_NONE = 0,
CGU_CLK_EXT = BIT(0),
CGU_CLK_PLL = BIT(1),
CGU_CLK_GATE = BIT(2),
CGU_CLK_MUX = BIT(3),
CGU_CLK_MUX_GLITCHFREE = BIT(4),
CGU_CLK_DIV = BIT(5),
CGU_CLK_FIXDIV = BIT(6),
CGU_CLK_CUSTOM = BIT(7),
} type;
int parents[4];
union {
struct ingenic_cgu_pll_info pll;
struct {
struct ingenic_cgu_gate_info gate;
struct ingenic_cgu_mux_info mux;
struct ingenic_cgu_div_info div;
struct ingenic_cgu_fixdiv_info fixdiv;
};
struct ingenic_cgu_custom_info custom;
};
};
Currently, such struct is documented as:
**Definition**
::
struct ingenic_cgu_clk_info {
const char * name;
};
**Members**
``name``
name of the clock
With is obvioulsy wrong. It also generates an error:
drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum'
However, there's nothing wrong with this kernel-doc markup: everything
is documented there.
It makes sense to document all fields there. So, add a
way for the core to parse those structs.
With this patch, all documented fields will properly generate
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:13 -07:00
|
|
|
'definition' => $declaration,
|
2005-04-16 16:20:36 -06:00
|
|
|
'parameterlist' => \@parameterlist,
|
|
|
|
'parameterdescs' => \%parameterdescs,
|
|
|
|
'parametertypes' => \%parametertypes,
|
|
|
|
'sectionlist' => \@sectionlist,
|
|
|
|
'sections' => \%sections,
|
|
|
|
'purpose' => $declaration_purpose,
|
|
|
|
'type' => $decl_type
|
|
|
|
});
|
|
|
|
}
|
|
|
|
else {
|
2015-09-04 16:43:21 -06:00
|
|
|
print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
++$errors;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2017-12-30 17:32:55 -07:00
|
|
|
|
|
|
|
sub show_warnings($$) {
|
|
|
|
my $functype = shift;
|
|
|
|
my $name = shift;
|
|
|
|
|
|
|
|
return 1 if ($output_selection == OUTPUT_ALL);
|
|
|
|
|
|
|
|
if ($output_selection == OUTPUT_EXPORTED) {
|
|
|
|
if (defined($function_table{$name})) {
|
|
|
|
return 1;
|
|
|
|
} else {
|
|
|
|
return 0;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
if ($output_selection == OUTPUT_INTERNAL) {
|
|
|
|
if (!($functype eq "function" && defined($function_table{$name}))) {
|
|
|
|
return 1;
|
|
|
|
} else {
|
|
|
|
return 0;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
if ($output_selection == OUTPUT_INCLUDE) {
|
|
|
|
if (defined($function_table{$name})) {
|
|
|
|
return 1;
|
|
|
|
} else {
|
|
|
|
return 0;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
if ($output_selection == OUTPUT_EXCLUDE) {
|
|
|
|
if (!defined($function_table{$name})) {
|
|
|
|
return 1;
|
|
|
|
} else {
|
|
|
|
return 0;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
die("Please add the new output type at show_warnings()");
|
|
|
|
}
|
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
sub dump_enum($$) {
|
|
|
|
my $x = shift;
|
|
|
|
my $file = shift;
|
|
|
|
|
2005-11-13 17:08:13 -07:00
|
|
|
$x =~ s@/\*.*?\*/@@gos; # strip comments.
|
2015-11-08 02:48:05 -07:00
|
|
|
# strip #define macros inside enums
|
|
|
|
$x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
|
2010-08-10 19:02:50 -06:00
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
|
2007-05-08 01:24:39 -06:00
|
|
|
$declaration_name = $1;
|
|
|
|
my $members = $2;
|
2017-09-19 05:08:13 -06:00
|
|
|
my %_members;
|
|
|
|
|
2017-06-16 13:27:48 -06:00
|
|
|
$members =~ s/\s+$//;
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
foreach my $arg (split ',', $members) {
|
|
|
|
$arg =~ s/^\s*(\w+).*/$1/;
|
|
|
|
push @parameterlist, $arg;
|
|
|
|
if (!$parameterdescs{$arg}) {
|
2007-05-08 01:24:39 -06:00
|
|
|
$parameterdescs{$arg} = $undescribed;
|
2017-12-30 17:32:55 -07:00
|
|
|
if (show_warnings("enum", $declaration_name)) {
|
2017-12-18 05:30:18 -07:00
|
|
|
print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum '$declaration_name'\n";
|
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
2017-09-19 05:08:13 -06:00
|
|
|
$_members{$arg} = 1;
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
2006-02-01 04:06:58 -07:00
|
|
|
|
2017-09-19 05:08:13 -06:00
|
|
|
while (my ($k, $v) = each %parameterdescs) {
|
|
|
|
if (!exists($_members{$k})) {
|
2017-12-30 17:32:55 -07:00
|
|
|
if (show_warnings("enum", $declaration_name)) {
|
2017-12-18 05:30:18 -07:00
|
|
|
print STDERR "${file}:$.: warning: Excess enum value '$k' description in '$declaration_name'\n";
|
|
|
|
}
|
2017-09-19 05:08:13 -06:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
output_declaration($declaration_name,
|
|
|
|
'enum',
|
|
|
|
{'enum' => $declaration_name,
|
|
|
|
'module' => $modulename,
|
|
|
|
'parameterlist' => \@parameterlist,
|
|
|
|
'parameterdescs' => \%parameterdescs,
|
|
|
|
'sectionlist' => \@sectionlist,
|
|
|
|
'sections' => \%sections,
|
|
|
|
'purpose' => $declaration_purpose
|
|
|
|
});
|
|
|
|
}
|
|
|
|
else {
|
2015-09-04 16:43:21 -06:00
|
|
|
print STDERR "${file}:$.: error: Cannot parse enum!\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
++$errors;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
sub dump_typedef($$) {
|
|
|
|
my $x = shift;
|
|
|
|
my $file = shift;
|
|
|
|
|
2005-11-13 17:08:13 -07:00
|
|
|
$x =~ s@/\*.*?\*/@@gos; # strip comments.
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2015-10-08 13:14:45 -06:00
|
|
|
# Parse function prototypes
|
2016-08-30 17:20:57 -06:00
|
|
|
if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
|
|
|
|
$x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
|
|
|
|
|
2015-10-08 13:14:45 -06:00
|
|
|
# Function typedefs
|
|
|
|
$return_type = $1;
|
|
|
|
$declaration_name = $2;
|
|
|
|
my $args = $3;
|
|
|
|
|
scripts: kernel-doc: print the declaration name on warnings
The logic at create_parameterlist()'s ancillary push_parameter()
function has already a way to output the declaration name, with
would help to discover what declaration is missing.
However, currently, the logic is utterly broken, as it uses
the var $type with a wrong meaning. With the current code,
it will never print anything. I suspect that originally
it was using the second argument of output_declaration().
I opted to not rely on a globally defined $declaration_name,
but, instead, to pass it explicitly as a parameter.
While here, I removed a unaligned check for !$anon_struct_union.
This is not needed, as, if $anon_struct_union is not zero,
$parameterdescs{$param} will be defined.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:15 -07:00
|
|
|
create_parameterlist($args, ',', $file, $declaration_name);
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
output_declaration($declaration_name,
|
2015-10-08 13:14:45 -06:00
|
|
|
'function',
|
|
|
|
{'function' => $declaration_name,
|
docs-rst: kernel-doc: fix typedef output in RST format
When using a typedef function like this one:
typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);
The Sphinx C domain expects it to create a c:type: reference,
as that's the way it creates the type references when parsing
a c:function:: declaration.
So, a declaration like:
.. c:function:: bool v4l2_valid_dv_timings (const struct v4l2_dv_timings * t, const struct v4l2_dv_timings_cap * cap, v4l2_check_dv_timings_fnc fnc, void * fnc_handle)
Will create a cross reference for :c:type:`v4l2_check_dv_timings_fnc`.
So, when outputting such typedefs in RST format, we need to handle
this special case, as otherwise it will produce those warnings:
./include/media/v4l2-dv-timings.h:43: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
./include/media/v4l2-dv-timings.h:60: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
./include/media/v4l2-dv-timings.h:81: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
So, change the kernel-doc script to produce a RST output for the
above typedef as:
.. c:type:: v4l2_check_dv_timings_fnc
**Typedef**: timings check callback
**Syntax**
``bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);``
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-30 17:20:58 -06:00
|
|
|
'typedef' => 1,
|
2005-04-16 16:20:36 -06:00
|
|
|
'module' => $modulename,
|
2015-10-08 13:14:45 -06:00
|
|
|
'functiontype' => $return_type,
|
|
|
|
'parameterlist' => \@parameterlist,
|
|
|
|
'parameterdescs' => \%parameterdescs,
|
|
|
|
'parametertypes' => \%parametertypes,
|
2005-04-16 16:20:36 -06:00
|
|
|
'sectionlist' => \@sectionlist,
|
|
|
|
'sections' => \%sections,
|
|
|
|
'purpose' => $declaration_purpose
|
|
|
|
});
|
2015-10-08 13:14:45 -06:00
|
|
|
return;
|
|
|
|
}
|
|
|
|
|
|
|
|
while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
|
|
|
|
$x =~ s/\(*.\)\s*;$/;/;
|
|
|
|
$x =~ s/\[*.\]\s*;$/;/;
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
2015-10-08 13:14:45 -06:00
|
|
|
|
|
|
|
if ($x =~ /typedef.*\s+(\w+)\s*;/) {
|
2015-10-08 12:21:44 -06:00
|
|
|
$declaration_name = $1;
|
|
|
|
|
|
|
|
output_declaration($declaration_name,
|
|
|
|
'typedef',
|
|
|
|
{'typedef' => $declaration_name,
|
|
|
|
'module' => $modulename,
|
|
|
|
'sectionlist' => \@sectionlist,
|
|
|
|
'sections' => \%sections,
|
|
|
|
'purpose' => $declaration_purpose
|
|
|
|
});
|
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
else {
|
2015-09-04 16:43:21 -06:00
|
|
|
print STDERR "${file}:$.: error: Cannot parse typedef!\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
++$errors;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2008-12-19 09:49:30 -07:00
|
|
|
sub save_struct_actual($) {
|
|
|
|
my $actual = shift;
|
|
|
|
|
|
|
|
# strip all spaces from the actual param so that it looks like one string item
|
|
|
|
$actual =~ s/\s*//g;
|
|
|
|
$struct_actual = $struct_actual . $actual . " ";
|
|
|
|
}
|
|
|
|
|
scripts: kernel-doc: print the declaration name on warnings
The logic at create_parameterlist()'s ancillary push_parameter()
function has already a way to output the declaration name, with
would help to discover what declaration is missing.
However, currently, the logic is utterly broken, as it uses
the var $type with a wrong meaning. With the current code,
it will never print anything. I suspect that originally
it was using the second argument of output_declaration().
I opted to not rely on a globally defined $declaration_name,
but, instead, to pass it explicitly as a parameter.
While here, I removed a unaligned check for !$anon_struct_union.
This is not needed, as, if $anon_struct_union is not zero,
$parameterdescs{$param} will be defined.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:15 -07:00
|
|
|
sub create_parameterlist($$$$) {
|
2005-04-16 16:20:36 -06:00
|
|
|
my $args = shift;
|
|
|
|
my $splitter = shift;
|
|
|
|
my $file = shift;
|
scripts: kernel-doc: print the declaration name on warnings
The logic at create_parameterlist()'s ancillary push_parameter()
function has already a way to output the declaration name, with
would help to discover what declaration is missing.
However, currently, the logic is utterly broken, as it uses
the var $type with a wrong meaning. With the current code,
it will never print anything. I suspect that originally
it was using the second argument of output_declaration().
I opted to not rely on a globally defined $declaration_name,
but, instead, to pass it explicitly as a parameter.
While here, I removed a unaligned check for !$anon_struct_union.
This is not needed, as, if $anon_struct_union is not zero,
$parameterdescs{$param} will be defined.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:15 -07:00
|
|
|
my $declaration_name = shift;
|
2005-04-16 16:20:36 -06:00
|
|
|
my $type;
|
|
|
|
my $param;
|
|
|
|
|
2006-01-09 21:53:55 -07:00
|
|
|
# temporarily replace commas inside function pointer definition
|
2005-04-16 16:20:36 -06:00
|
|
|
while ($args =~ /(\([^\),]+),/) {
|
2007-05-08 01:24:39 -06:00
|
|
|
$args =~ s/(\([^\),]+),/$1#/g;
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
2006-02-01 04:06:58 -07:00
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
foreach my $arg (split($splitter, $args)) {
|
|
|
|
# strip comments
|
|
|
|
$arg =~ s/\/\*.*\*\///;
|
2007-05-08 01:24:39 -06:00
|
|
|
# strip leading/trailing spaces
|
|
|
|
$arg =~ s/^\s*//;
|
2005-04-16 16:20:36 -06:00
|
|
|
$arg =~ s/\s*$//;
|
|
|
|
$arg =~ s/\s+/ /;
|
|
|
|
|
|
|
|
if ($arg =~ /^#/) {
|
|
|
|
# Treat preprocessor directive as a typeless variable just to fill
|
|
|
|
# corresponding data structures "correctly". Catch it later in
|
|
|
|
# output_* subs.
|
|
|
|
push_parameter($arg, "", $file);
|
2008-02-23 16:24:01 -07:00
|
|
|
} elsif ($arg =~ m/\(.+\)\s*\(/) {
|
2005-04-16 16:20:36 -06:00
|
|
|
# pointer-to-function
|
|
|
|
$arg =~ tr/#/,/;
|
2017-12-18 05:30:16 -07:00
|
|
|
$arg =~ m/[^\(]+\(\*?\s*([\w\.]*)\s*\)/;
|
2005-04-16 16:20:36 -06:00
|
|
|
$param = $1;
|
|
|
|
$type = $arg;
|
2008-02-23 16:24:01 -07:00
|
|
|
$type =~ s/([^\(]+\(\*?)\s*$param/$1/;
|
2008-12-19 09:49:30 -07:00
|
|
|
save_struct_actual($param);
|
scripts: kernel-doc: print the declaration name on warnings
The logic at create_parameterlist()'s ancillary push_parameter()
function has already a way to output the declaration name, with
would help to discover what declaration is missing.
However, currently, the logic is utterly broken, as it uses
the var $type with a wrong meaning. With the current code,
it will never print anything. I suspect that originally
it was using the second argument of output_declaration().
I opted to not rely on a globally defined $declaration_name,
but, instead, to pass it explicitly as a parameter.
While here, I removed a unaligned check for !$anon_struct_union.
This is not needed, as, if $anon_struct_union is not zero,
$parameterdescs{$param} will be defined.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:15 -07:00
|
|
|
push_parameter($param, $type, $file, $declaration_name);
|
2005-11-13 17:08:13 -07:00
|
|
|
} elsif ($arg) {
|
2005-04-16 16:20:36 -06:00
|
|
|
$arg =~ s/\s*:\s*/:/g;
|
|
|
|
$arg =~ s/\s*\[/\[/g;
|
|
|
|
|
|
|
|
my @args = split('\s*,\s*', $arg);
|
|
|
|
if ($args[0] =~ m/\*/) {
|
|
|
|
$args[0] =~ s/(\*+)\s*/ $1/;
|
|
|
|
}
|
2007-05-08 01:29:05 -06:00
|
|
|
|
|
|
|
my @first_arg;
|
|
|
|
if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
|
|
|
|
shift @args;
|
|
|
|
push(@first_arg, split('\s+', $1));
|
|
|
|
push(@first_arg, $2);
|
|
|
|
} else {
|
|
|
|
@first_arg = split('\s+', shift @args);
|
|
|
|
}
|
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
unshift(@args, pop @first_arg);
|
|
|
|
$type = join " ", @first_arg;
|
|
|
|
|
|
|
|
foreach $param (@args) {
|
|
|
|
if ($param =~ m/^(\*+)\s*(.*)/) {
|
2008-12-19 09:49:30 -07:00
|
|
|
save_struct_actual($2);
|
scripts: kernel-doc: print the declaration name on warnings
The logic at create_parameterlist()'s ancillary push_parameter()
function has already a way to output the declaration name, with
would help to discover what declaration is missing.
However, currently, the logic is utterly broken, as it uses
the var $type with a wrong meaning. With the current code,
it will never print anything. I suspect that originally
it was using the second argument of output_declaration().
I opted to not rely on a globally defined $declaration_name,
but, instead, to pass it explicitly as a parameter.
While here, I removed a unaligned check for !$anon_struct_union.
This is not needed, as, if $anon_struct_union is not zero,
$parameterdescs{$param} will be defined.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:15 -07:00
|
|
|
push_parameter($2, "$type $1", $file, $declaration_name);
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
|
|
|
elsif ($param =~ m/(.*?):(\d+)/) {
|
2008-05-16 16:45:52 -06:00
|
|
|
if ($type ne "") { # skip unnamed bit-fields
|
2008-12-19 09:49:30 -07:00
|
|
|
save_struct_actual($1);
|
scripts: kernel-doc: print the declaration name on warnings
The logic at create_parameterlist()'s ancillary push_parameter()
function has already a way to output the declaration name, with
would help to discover what declaration is missing.
However, currently, the logic is utterly broken, as it uses
the var $type with a wrong meaning. With the current code,
it will never print anything. I suspect that originally
it was using the second argument of output_declaration().
I opted to not rely on a globally defined $declaration_name,
but, instead, to pass it explicitly as a parameter.
While here, I removed a unaligned check for !$anon_struct_union.
This is not needed, as, if $anon_struct_union is not zero,
$parameterdescs{$param} will be defined.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:15 -07:00
|
|
|
push_parameter($1, "$type:$2", $file, $declaration_name)
|
2008-05-16 16:45:52 -06:00
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
|
|
|
else {
|
2008-12-19 09:49:30 -07:00
|
|
|
save_struct_actual($param);
|
scripts: kernel-doc: print the declaration name on warnings
The logic at create_parameterlist()'s ancillary push_parameter()
function has already a way to output the declaration name, with
would help to discover what declaration is missing.
However, currently, the logic is utterly broken, as it uses
the var $type with a wrong meaning. With the current code,
it will never print anything. I suspect that originally
it was using the second argument of output_declaration().
I opted to not rely on a globally defined $declaration_name,
but, instead, to pass it explicitly as a parameter.
While here, I removed a unaligned check for !$anon_struct_union.
This is not needed, as, if $anon_struct_union is not zero,
$parameterdescs{$param} will be defined.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:15 -07:00
|
|
|
push_parameter($param, $type, $file, $declaration_name);
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
scripts: kernel-doc: print the declaration name on warnings
The logic at create_parameterlist()'s ancillary push_parameter()
function has already a way to output the declaration name, with
would help to discover what declaration is missing.
However, currently, the logic is utterly broken, as it uses
the var $type with a wrong meaning. With the current code,
it will never print anything. I suspect that originally
it was using the second argument of output_declaration().
I opted to not rely on a globally defined $declaration_name,
but, instead, to pass it explicitly as a parameter.
While here, I removed a unaligned check for !$anon_struct_union.
This is not needed, as, if $anon_struct_union is not zero,
$parameterdescs{$param} will be defined.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:15 -07:00
|
|
|
sub push_parameter($$$$) {
|
2005-04-16 16:20:36 -06:00
|
|
|
my $param = shift;
|
|
|
|
my $type = shift;
|
|
|
|
my $file = shift;
|
scripts: kernel-doc: print the declaration name on warnings
The logic at create_parameterlist()'s ancillary push_parameter()
function has already a way to output the declaration name, with
would help to discover what declaration is missing.
However, currently, the logic is utterly broken, as it uses
the var $type with a wrong meaning. With the current code,
it will never print anything. I suspect that originally
it was using the second argument of output_declaration().
I opted to not rely on a globally defined $declaration_name,
but, instead, to pass it explicitly as a parameter.
While here, I removed a unaligned check for !$anon_struct_union.
This is not needed, as, if $anon_struct_union is not zero,
$parameterdescs{$param} will be defined.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:15 -07:00
|
|
|
my $declaration_name = shift;
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2007-07-19 02:48:24 -06:00
|
|
|
if (($anon_struct_union == 1) && ($type eq "") &&
|
|
|
|
($param eq "}")) {
|
|
|
|
return; # ignore the ending }; from anon. struct/union
|
|
|
|
}
|
|
|
|
|
|
|
|
$anon_struct_union = 0;
|
2017-03-30 14:11:29 -06:00
|
|
|
$param =~ s/[\[\)].*//;
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2006-01-09 21:53:55 -07:00
|
|
|
if ($type eq "" && $param =~ /\.\.\.$/)
|
2005-04-16 16:20:36 -06:00
|
|
|
{
|
2016-10-28 02:14:08 -06:00
|
|
|
if (!$param =~ /\w\.\.\.$/) {
|
|
|
|
# handles unnamed variable parameters
|
|
|
|
$param = "...";
|
|
|
|
}
|
2008-12-01 14:14:03 -07:00
|
|
|
if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
|
|
|
|
$parameterdescs{$param} = "variable arguments";
|
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
|
|
|
elsif ($type eq "" && ($param eq "" or $param eq "void"))
|
|
|
|
{
|
|
|
|
$param="void";
|
|
|
|
$parameterdescs{void} = "no arguments";
|
|
|
|
}
|
2006-12-22 02:10:50 -07:00
|
|
|
elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
|
|
|
|
# handle unnamed (anonymous) union or struct:
|
|
|
|
{
|
|
|
|
$type = $param;
|
2007-07-19 02:48:24 -06:00
|
|
|
$param = "{unnamed_" . $param . "}";
|
2006-12-22 02:10:50 -07:00
|
|
|
$parameterdescs{$param} = "anonymous\n";
|
2007-07-19 02:48:24 -06:00
|
|
|
$anon_struct_union = 1;
|
2006-12-22 02:10:50 -07:00
|
|
|
}
|
|
|
|
|
2006-01-09 21:53:55 -07:00
|
|
|
# warn if parameter has no description
|
2006-12-22 02:10:50 -07:00
|
|
|
# (but ignore ones starting with # as these are not parameters
|
|
|
|
# but inline preprocessor statements);
|
scripts: kernel-doc: print the declaration name on warnings
The logic at create_parameterlist()'s ancillary push_parameter()
function has already a way to output the declaration name, with
would help to discover what declaration is missing.
However, currently, the logic is utterly broken, as it uses
the var $type with a wrong meaning. With the current code,
it will never print anything. I suspect that originally
it was using the second argument of output_declaration().
I opted to not rely on a globally defined $declaration_name,
but, instead, to pass it explicitly as a parameter.
While here, I removed a unaligned check for !$anon_struct_union.
This is not needed, as, if $anon_struct_union is not zero,
$parameterdescs{$param} will be defined.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:15 -07:00
|
|
|
# Note: It will also ignore void params and unnamed structs/unions
|
2017-03-30 14:11:29 -06:00
|
|
|
if (!defined $parameterdescs{$param} && $param !~ /^#/) {
|
scripts: kernel-doc: print the declaration name on warnings
The logic at create_parameterlist()'s ancillary push_parameter()
function has already a way to output the declaration name, with
would help to discover what declaration is missing.
However, currently, the logic is utterly broken, as it uses
the var $type with a wrong meaning. With the current code,
it will never print anything. I suspect that originally
it was using the second argument of output_declaration().
I opted to not rely on a globally defined $declaration_name,
but, instead, to pass it explicitly as a parameter.
While here, I removed a unaligned check for !$anon_struct_union.
This is not needed, as, if $anon_struct_union is not zero,
$parameterdescs{$param} will be defined.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:15 -07:00
|
|
|
$parameterdescs{$param} = $undescribed;
|
2006-01-09 21:53:55 -07:00
|
|
|
|
2017-12-30 17:32:55 -07:00
|
|
|
if (show_warnings($type, $declaration_name)) {
|
2017-12-18 05:30:18 -07:00
|
|
|
print STDERR
|
|
|
|
"${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
|
|
|
|
++$warnings;
|
|
|
|
}
|
2007-05-08 01:24:39 -06:00
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2010-11-18 13:27:31 -07:00
|
|
|
$param = xml_escape($param);
|
|
|
|
|
2011-03-30 19:57:33 -06:00
|
|
|
# strip spaces from $param so that it is one continuous string
|
2009-06-17 18:37:47 -06:00
|
|
|
# on @parameterlist;
|
|
|
|
# this fixes a problem where check_sections() cannot find
|
|
|
|
# a parameter like "addr[6 + 2]" because it actually appears
|
|
|
|
# as "addr[6", "+", "2]" on the parameter list;
|
|
|
|
# but it's better to maintain the param string unchanged for output,
|
|
|
|
# so just weaken the string compare in check_sections() to ignore
|
|
|
|
# "[blah" in a parameter string;
|
|
|
|
###$param =~ s/\s*//g;
|
2005-04-16 16:20:36 -06:00
|
|
|
push @parameterlist, $param;
|
2017-01-02 08:22:23 -07:00
|
|
|
$type =~ s/\s\s+/ /g;
|
2005-04-16 16:20:36 -06:00
|
|
|
$parametertypes{$param} = $type;
|
|
|
|
}
|
|
|
|
|
2017-12-18 05:30:14 -07:00
|
|
|
sub check_sections($$$$$) {
|
|
|
|
my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) = @_;
|
2008-12-19 09:49:30 -07:00
|
|
|
my @sects = split ' ', $sectcheck;
|
|
|
|
my @prms = split ' ', $prmscheck;
|
|
|
|
my $err;
|
|
|
|
my ($px, $sx);
|
|
|
|
my $prm_clean; # strip trailing "[array size]" and/or beginning "*"
|
|
|
|
|
|
|
|
foreach $sx (0 .. $#sects) {
|
|
|
|
$err = 1;
|
|
|
|
foreach $px (0 .. $#prms) {
|
|
|
|
$prm_clean = $prms[$px];
|
|
|
|
$prm_clean =~ s/\[.*\]//;
|
2010-09-11 16:55:12 -06:00
|
|
|
$prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
|
2009-06-17 18:37:47 -06:00
|
|
|
# ignore array size in a parameter string;
|
|
|
|
# however, the original param string may contain
|
|
|
|
# spaces, e.g.: addr[6 + 2]
|
|
|
|
# and this appears in @prms as "addr[6" since the
|
|
|
|
# parameter list is split at spaces;
|
|
|
|
# hence just ignore "[..." for the sections check;
|
|
|
|
$prm_clean =~ s/\[.*//;
|
|
|
|
|
2008-12-19 09:49:30 -07:00
|
|
|
##$prm_clean =~ s/^\**//;
|
|
|
|
if ($prm_clean eq $sects[$sx]) {
|
|
|
|
$err = 0;
|
|
|
|
last;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
if ($err) {
|
|
|
|
if ($decl_type eq "function") {
|
2015-09-04 16:43:21 -06:00
|
|
|
print STDERR "${file}:$.: warning: " .
|
2008-12-19 09:49:30 -07:00
|
|
|
"Excess function parameter " .
|
|
|
|
"'$sects[$sx]' " .
|
|
|
|
"description in '$decl_name'\n";
|
|
|
|
++$warnings;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2012-11-26 14:22:27 -07:00
|
|
|
##
|
|
|
|
# Checks the section describing the return value of a function.
|
|
|
|
sub check_return_section {
|
|
|
|
my $file = shift;
|
|
|
|
my $declaration_name = shift;
|
|
|
|
my $return_type = shift;
|
|
|
|
|
|
|
|
# Ignore an empty return type (It's a macro)
|
|
|
|
# Ignore functions with a "void" return type. (But don't ignore "void *")
|
|
|
|
if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
|
|
|
|
return;
|
|
|
|
}
|
|
|
|
|
|
|
|
if (!defined($sections{$section_return}) ||
|
|
|
|
$sections{$section_return} eq "") {
|
2015-09-04 16:43:21 -06:00
|
|
|
print STDERR "${file}:$.: warning: " .
|
2012-11-26 14:22:27 -07:00
|
|
|
"No description found for return value of " .
|
|
|
|
"'$declaration_name'\n";
|
|
|
|
++$warnings;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
##
|
|
|
|
# takes a function prototype and the name of the current file being
|
|
|
|
# processed and spits out all the details stored in the global
|
|
|
|
# arrays/hashes.
|
|
|
|
sub dump_function($$) {
|
|
|
|
my $prototype = shift;
|
|
|
|
my $file = shift;
|
2014-07-12 10:55:03 -06:00
|
|
|
my $noret = 0;
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
$prototype =~ s/^static +//;
|
|
|
|
$prototype =~ s/^extern +//;
|
2005-05-01 09:59:25 -06:00
|
|
|
$prototype =~ s/^asmlinkage +//;
|
2005-04-16 16:20:36 -06:00
|
|
|
$prototype =~ s/^inline +//;
|
|
|
|
$prototype =~ s/^__inline__ +//;
|
2006-10-11 02:22:10 -06:00
|
|
|
$prototype =~ s/^__inline +//;
|
|
|
|
$prototype =~ s/^__always_inline +//;
|
|
|
|
$prototype =~ s/^noinline +//;
|
2008-06-19 17:03:29 -06:00
|
|
|
$prototype =~ s/__init +//;
|
2010-03-23 14:35:24 -06:00
|
|
|
$prototype =~ s/__init_or_module +//;
|
2014-08-24 19:17:17 -06:00
|
|
|
$prototype =~ s/__meminit +//;
|
2012-01-21 11:31:54 -07:00
|
|
|
$prototype =~ s/__must_check +//;
|
2012-08-16 17:23:20 -06:00
|
|
|
$prototype =~ s/__weak +//;
|
2014-07-12 10:55:03 -06:00
|
|
|
my $define = $prototype =~ s/^#\s*define\s+//; #ak added
|
2017-01-02 08:22:24 -07:00
|
|
|
$prototype =~ s/__attribute__\s*\(\(
|
|
|
|
(?:
|
|
|
|
[\w\s]++ # attribute name
|
|
|
|
(?:\([^)]*+\))? # attribute arguments
|
|
|
|
\s*+,? # optional comma at the end
|
|
|
|
)+
|
|
|
|
\)\)\s+//x;
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
# Yes, this truly is vile. We are looking for:
|
|
|
|
# 1. Return type (may be nothing if we're looking at a macro)
|
|
|
|
# 2. Function name
|
|
|
|
# 3. Function parameters.
|
|
|
|
#
|
|
|
|
# All the while we have to watch out for function pointer parameters
|
|
|
|
# (which IIRC is what the two sections are for), C types (these
|
|
|
|
# regexps don't even start to express all the possibilities), and
|
|
|
|
# so on.
|
|
|
|
#
|
|
|
|
# If you mess with these regexps, it's a good idea to check that
|
|
|
|
# the following functions' documentation still comes out right:
|
|
|
|
# - parport_register_device (function pointer parameters)
|
|
|
|
# - atomic_set (macro)
|
2006-02-01 04:06:55 -07:00
|
|
|
# - pci_match_device, __copy_to_user (long return type)
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2014-07-12 10:55:03 -06:00
|
|
|
if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
|
|
|
|
# This is an object-like macro, it has no return type and no parameter
|
|
|
|
# list.
|
|
|
|
# Function-like macros are not allowed to have spaces between
|
|
|
|
# declaration_name and opening parenthesis (notice the \s+).
|
|
|
|
$return_type = $1;
|
|
|
|
$declaration_name = $2;
|
|
|
|
$noret = 1;
|
|
|
|
} elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
|
2005-04-16 16:20:36 -06:00
|
|
|
$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
|
2017-01-23 01:18:10 -07:00
|
|
|
$prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
|
2005-04-16 16:20:36 -06:00
|
|
|
$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
|
2008-02-07 01:13:26 -07:00
|
|
|
$prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
|
2005-04-16 16:20:36 -06:00
|
|
|
$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
|
2017-01-23 01:18:10 -07:00
|
|
|
$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
|
2005-04-16 16:20:36 -06:00
|
|
|
$prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
|
|
|
|
$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
|
2017-01-23 01:18:10 -07:00
|
|
|
$prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
|
2005-04-16 16:20:36 -06:00
|
|
|
$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
|
2017-01-23 01:18:10 -07:00
|
|
|
$prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
|
2005-04-16 16:20:36 -06:00
|
|
|
$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
|
2017-01-23 01:18:10 -07:00
|
|
|
$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
|
2006-02-01 04:06:55 -07:00
|
|
|
$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
|
2017-01-23 01:18:10 -07:00
|
|
|
$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
|
|
|
|
$prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
|
2005-04-16 16:20:36 -06:00
|
|
|
$return_type = $1;
|
|
|
|
$declaration_name = $2;
|
|
|
|
my $args = $3;
|
|
|
|
|
scripts: kernel-doc: print the declaration name on warnings
The logic at create_parameterlist()'s ancillary push_parameter()
function has already a way to output the declaration name, with
would help to discover what declaration is missing.
However, currently, the logic is utterly broken, as it uses
the var $type with a wrong meaning. With the current code,
it will never print anything. I suspect that originally
it was using the second argument of output_declaration().
I opted to not rely on a globally defined $declaration_name,
but, instead, to pass it explicitly as a parameter.
While here, I removed a unaligned check for !$anon_struct_union.
This is not needed, as, if $anon_struct_union is not zero,
$parameterdescs{$param} will be defined.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-18 05:30:15 -07:00
|
|
|
create_parameterlist($args, ',', $file, $declaration_name);
|
2005-04-16 16:20:36 -06:00
|
|
|
} else {
|
2015-09-04 16:43:21 -06:00
|
|
|
print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
return;
|
|
|
|
}
|
|
|
|
|
2008-12-19 09:49:30 -07:00
|
|
|
my $prms = join " ", @parameterlist;
|
2017-12-18 05:30:14 -07:00
|
|
|
check_sections($file, $declaration_name, "function", $sectcheck, $prms);
|
2008-12-19 09:49:30 -07:00
|
|
|
|
2012-11-26 14:22:27 -07:00
|
|
|
# This check emits a lot of warnings at the moment, because many
|
|
|
|
# functions don't have a 'Return' doc section. So until the number
|
|
|
|
# of warnings goes sufficiently down, the check is only performed in
|
|
|
|
# verbose mode.
|
|
|
|
# TODO: always perform the check.
|
2014-07-12 10:55:03 -06:00
|
|
|
if ($verbose && !$noret) {
|
2012-11-26 14:22:27 -07:00
|
|
|
check_return_section($file, $declaration_name, $return_type);
|
|
|
|
}
|
|
|
|
|
2006-02-01 04:06:58 -07:00
|
|
|
output_declaration($declaration_name,
|
2005-04-16 16:20:36 -06:00
|
|
|
'function',
|
|
|
|
{'function' => $declaration_name,
|
|
|
|
'module' => $modulename,
|
|
|
|
'functiontype' => $return_type,
|
|
|
|
'parameterlist' => \@parameterlist,
|
|
|
|
'parameterdescs' => \%parameterdescs,
|
|
|
|
'parametertypes' => \%parametertypes,
|
|
|
|
'sectionlist' => \@sectionlist,
|
|
|
|
'sections' => \%sections,
|
|
|
|
'purpose' => $declaration_purpose
|
|
|
|
});
|
|
|
|
}
|
|
|
|
|
|
|
|
sub reset_state {
|
|
|
|
$function = "";
|
|
|
|
%parameterdescs = ();
|
|
|
|
%parametertypes = ();
|
|
|
|
@parameterlist = ();
|
|
|
|
%sections = ();
|
|
|
|
@sectionlist = ();
|
2008-12-19 09:49:30 -07:00
|
|
|
$sectcheck = "";
|
|
|
|
$struct_actual = "";
|
2005-04-16 16:20:36 -06:00
|
|
|
$prototype = "";
|
2006-02-01 04:06:58 -07:00
|
|
|
|
2016-05-26 05:56:05 -06:00
|
|
|
$state = STATE_NORMAL;
|
|
|
|
$inline_doc_state = STATE_INLINE_NA;
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
|
|
|
|
2009-04-30 11:29:36 -06:00
|
|
|
sub tracepoint_munge($) {
|
|
|
|
my $file = shift;
|
|
|
|
my $tracepointname = 0;
|
|
|
|
my $tracepointargs = 0;
|
|
|
|
|
2009-12-01 10:18:49 -07:00
|
|
|
if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
|
2009-04-30 11:29:36 -06:00
|
|
|
$tracepointname = $1;
|
|
|
|
}
|
2009-12-01 10:18:49 -07:00
|
|
|
if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
|
|
|
|
$tracepointname = $1;
|
|
|
|
}
|
|
|
|
if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
|
|
|
|
$tracepointname = $2;
|
|
|
|
}
|
|
|
|
$tracepointname =~ s/^\s+//; #strip leading whitespace
|
|
|
|
if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
|
2009-04-30 11:29:36 -06:00
|
|
|
$tracepointargs = $1;
|
|
|
|
}
|
|
|
|
if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
|
2015-09-04 16:43:21 -06:00
|
|
|
print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
|
2009-04-30 11:29:36 -06:00
|
|
|
"$prototype\n";
|
|
|
|
} else {
|
|
|
|
$prototype = "static inline void trace_$tracepointname($tracepointargs)";
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
kernel-doc: fix syscall wrapper processing
Fix kernel-doc processing of SYSCALL wrappers.
The SYSCALL wrapper patches played havoc with kernel-doc for
syscalls. Syscalls that were scanned for DocBook processing
reported warnings like this one, for sys_tgkill:
Warning(kernel/signal.c:2285): No description found for parameter 'tgkill'
Warning(kernel/signal.c:2285): No description found for parameter 'pid_t'
Warning(kernel/signal.c:2285): No description found for parameter 'int'
because the macro parameters all "look like" function parameters,
although they are not:
/**
* sys_tgkill - send signal to one specific thread
* @tgid: the thread group ID of the thread
* @pid: the PID of the thread
* @sig: signal to be sent
*
* This syscall also checks the @tgid and returns -ESRCH even if the PID
* exists but it's not belonging to the target process anymore. This
* method solves the problem of threads exiting and PIDs getting reused.
*/
SYSCALL_DEFINE3(tgkill, pid_t, tgid, pid_t, pid, int, sig)
{
...
This patch special-cases the handling SYSCALL_DEFINE* function
prototypes by expanding them to
long sys_foobar(type1 arg1, type1 arg2, ...)
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2009-02-11 14:04:33 -07:00
|
|
|
sub syscall_munge() {
|
|
|
|
my $void = 0;
|
|
|
|
|
2017-12-18 05:30:12 -07:00
|
|
|
$prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's
|
kernel-doc: fix syscall wrapper processing
Fix kernel-doc processing of SYSCALL wrappers.
The SYSCALL wrapper patches played havoc with kernel-doc for
syscalls. Syscalls that were scanned for DocBook processing
reported warnings like this one, for sys_tgkill:
Warning(kernel/signal.c:2285): No description found for parameter 'tgkill'
Warning(kernel/signal.c:2285): No description found for parameter 'pid_t'
Warning(kernel/signal.c:2285): No description found for parameter 'int'
because the macro parameters all "look like" function parameters,
although they are not:
/**
* sys_tgkill - send signal to one specific thread
* @tgid: the thread group ID of the thread
* @pid: the PID of the thread
* @sig: signal to be sent
*
* This syscall also checks the @tgid and returns -ESRCH even if the PID
* exists but it's not belonging to the target process anymore. This
* method solves the problem of threads exiting and PIDs getting reused.
*/
SYSCALL_DEFINE3(tgkill, pid_t, tgid, pid_t, pid, int, sig)
{
...
This patch special-cases the handling SYSCALL_DEFINE* function
prototypes by expanding them to
long sys_foobar(type1 arg1, type1 arg2, ...)
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2009-02-11 14:04:33 -07:00
|
|
|
## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
|
|
|
|
if ($prototype =~ m/SYSCALL_DEFINE0/) {
|
|
|
|
$void = 1;
|
|
|
|
## $prototype = "long sys_$1(void)";
|
|
|
|
}
|
|
|
|
|
|
|
|
$prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
|
|
|
|
if ($prototype =~ m/long (sys_.*?),/) {
|
|
|
|
$prototype =~ s/,/\(/;
|
|
|
|
} elsif ($void) {
|
|
|
|
$prototype =~ s/\)/\(void\)/;
|
|
|
|
}
|
|
|
|
|
|
|
|
# now delete all of the odd-number commas in $prototype
|
|
|
|
# so that arg types & arg names don't have a comma between them
|
|
|
|
my $count = 0;
|
|
|
|
my $len = length($prototype);
|
|
|
|
if ($void) {
|
|
|
|
$len = 0; # skip the for-loop
|
|
|
|
}
|
|
|
|
for (my $ix = 0; $ix < $len; $ix++) {
|
|
|
|
if (substr($prototype, $ix, 1) eq ',') {
|
|
|
|
$count++;
|
|
|
|
if ($count % 2 == 1) {
|
|
|
|
substr($prototype, $ix, 1) = ' ';
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2016-06-01 15:46:24 -06:00
|
|
|
sub process_proto_function($$) {
|
2005-04-16 16:20:36 -06:00
|
|
|
my $x = shift;
|
|
|
|
my $file = shift;
|
|
|
|
|
2007-07-19 02:48:24 -06:00
|
|
|
$x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
|
|
|
|
|
2008-10-25 18:06:43 -06:00
|
|
|
if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
|
2005-04-16 16:20:36 -06:00
|
|
|
# do nothing
|
|
|
|
}
|
|
|
|
elsif ($x =~ /([^\{]*)/) {
|
2007-05-08 01:24:39 -06:00
|
|
|
$prototype .= $1;
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
kernel-doc: fix syscall wrapper processing
Fix kernel-doc processing of SYSCALL wrappers.
The SYSCALL wrapper patches played havoc with kernel-doc for
syscalls. Syscalls that were scanned for DocBook processing
reported warnings like this one, for sys_tgkill:
Warning(kernel/signal.c:2285): No description found for parameter 'tgkill'
Warning(kernel/signal.c:2285): No description found for parameter 'pid_t'
Warning(kernel/signal.c:2285): No description found for parameter 'int'
because the macro parameters all "look like" function parameters,
although they are not:
/**
* sys_tgkill - send signal to one specific thread
* @tgid: the thread group ID of the thread
* @pid: the PID of the thread
* @sig: signal to be sent
*
* This syscall also checks the @tgid and returns -ESRCH even if the PID
* exists but it's not belonging to the target process anymore. This
* method solves the problem of threads exiting and PIDs getting reused.
*/
SYSCALL_DEFINE3(tgkill, pid_t, tgid, pid_t, pid, int, sig)
{
...
This patch special-cases the handling SYSCALL_DEFINE* function
prototypes by expanding them to
long sys_foobar(type1 arg1, type1 arg2, ...)
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2009-02-11 14:04:33 -07:00
|
|
|
|
2008-10-25 18:06:43 -06:00
|
|
|
if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
|
2007-05-08 01:24:39 -06:00
|
|
|
$prototype =~ s@/\*.*?\*/@@gos; # strip comments.
|
2005-04-16 16:20:36 -06:00
|
|
|
$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
|
|
|
|
$prototype =~ s@^\s+@@gos; # strip leading spaces
|
kernel-doc: fix syscall wrapper processing
Fix kernel-doc processing of SYSCALL wrappers.
The SYSCALL wrapper patches played havoc with kernel-doc for
syscalls. Syscalls that were scanned for DocBook processing
reported warnings like this one, for sys_tgkill:
Warning(kernel/signal.c:2285): No description found for parameter 'tgkill'
Warning(kernel/signal.c:2285): No description found for parameter 'pid_t'
Warning(kernel/signal.c:2285): No description found for parameter 'int'
because the macro parameters all "look like" function parameters,
although they are not:
/**
* sys_tgkill - send signal to one specific thread
* @tgid: the thread group ID of the thread
* @pid: the PID of the thread
* @sig: signal to be sent
*
* This syscall also checks the @tgid and returns -ESRCH even if the PID
* exists but it's not belonging to the target process anymore. This
* method solves the problem of threads exiting and PIDs getting reused.
*/
SYSCALL_DEFINE3(tgkill, pid_t, tgid, pid_t, pid, int, sig)
{
...
This patch special-cases the handling SYSCALL_DEFINE* function
prototypes by expanding them to
long sys_foobar(type1 arg1, type1 arg2, ...)
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2009-02-11 14:04:33 -07:00
|
|
|
if ($prototype =~ /SYSCALL_DEFINE/) {
|
|
|
|
syscall_munge();
|
|
|
|
}
|
2009-12-01 10:18:49 -07:00
|
|
|
if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
|
|
|
|
$prototype =~ /DEFINE_SINGLE_EVENT/)
|
|
|
|
{
|
2009-04-30 11:29:36 -06:00
|
|
|
tracepoint_munge($file);
|
|
|
|
}
|
kernel-doc: fix syscall wrapper processing
Fix kernel-doc processing of SYSCALL wrappers.
The SYSCALL wrapper patches played havoc with kernel-doc for
syscalls. Syscalls that were scanned for DocBook processing
reported warnings like this one, for sys_tgkill:
Warning(kernel/signal.c:2285): No description found for parameter 'tgkill'
Warning(kernel/signal.c:2285): No description found for parameter 'pid_t'
Warning(kernel/signal.c:2285): No description found for parameter 'int'
because the macro parameters all "look like" function parameters,
although they are not:
/**
* sys_tgkill - send signal to one specific thread
* @tgid: the thread group ID of the thread
* @pid: the PID of the thread
* @sig: signal to be sent
*
* This syscall also checks the @tgid and returns -ESRCH even if the PID
* exists but it's not belonging to the target process anymore. This
* method solves the problem of threads exiting and PIDs getting reused.
*/
SYSCALL_DEFINE3(tgkill, pid_t, tgid, pid_t, pid, int, sig)
{
...
This patch special-cases the handling SYSCALL_DEFINE* function
prototypes by expanding them to
long sys_foobar(type1 arg1, type1 arg2, ...)
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2009-02-11 14:04:33 -07:00
|
|
|
dump_function($prototype, $file);
|
2005-04-16 16:20:36 -06:00
|
|
|
reset_state();
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2016-06-01 15:46:24 -06:00
|
|
|
sub process_proto_type($$) {
|
2005-04-16 16:20:36 -06:00
|
|
|
my $x = shift;
|
|
|
|
my $file = shift;
|
|
|
|
|
|
|
|
$x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
|
|
|
|
$x =~ s@^\s+@@gos; # strip leading spaces
|
|
|
|
$x =~ s@\s+$@@gos; # strip trailing spaces
|
2007-07-19 02:48:24 -06:00
|
|
|
$x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
|
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
if ($x =~ /^#/) {
|
|
|
|
# To distinguish preprocessor directive from regular declaration later.
|
|
|
|
$x .= ";";
|
|
|
|
}
|
|
|
|
|
|
|
|
while (1) {
|
2007-05-08 01:24:39 -06:00
|
|
|
if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
|
2017-06-16 13:27:48 -06:00
|
|
|
if( length $prototype ) {
|
|
|
|
$prototype .= " "
|
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
$prototype .= $1 . $2;
|
|
|
|
($2 eq '{') && $brcount++;
|
|
|
|
($2 eq '}') && $brcount--;
|
|
|
|
if (($2 eq ';') && ($brcount == 0)) {
|
2009-06-09 09:50:38 -06:00
|
|
|
dump_declaration($prototype, $file);
|
2005-04-16 16:20:36 -06:00
|
|
|
reset_state();
|
2007-05-08 01:24:39 -06:00
|
|
|
last;
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
|
|
|
$x = $3;
|
2007-05-08 01:24:39 -06:00
|
|
|
} else {
|
2005-04-16 16:20:36 -06:00
|
|
|
$prototype .= $x;
|
|
|
|
last;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2007-10-17 00:31:20 -06:00
|
|
|
# xml_escape: replace <, >, and & in the text stream;
|
|
|
|
#
|
|
|
|
# however, formatting controls that are generated internally/locally in the
|
|
|
|
# kernel-doc script are not escaped here; instead, they begin life like
|
|
|
|
# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
|
|
|
|
# are converted to their mnemonic-expected output, without the 4 * '\' & ':',
|
|
|
|
# just before actual output; (this is done by local_unescape())
|
2005-04-16 16:20:36 -06:00
|
|
|
sub xml_escape($) {
|
|
|
|
my $text = shift;
|
2017-12-18 05:30:09 -07:00
|
|
|
if ($output_mode eq "man") {
|
2006-06-25 06:49:13 -06:00
|
|
|
return $text;
|
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
$text =~ s/\&/\\\\\\amp;/g;
|
|
|
|
$text =~ s/\</\\\\\\lt;/g;
|
|
|
|
$text =~ s/\>/\\\\\\gt;/g;
|
|
|
|
return $text;
|
|
|
|
}
|
|
|
|
|
2016-05-12 07:15:37 -06:00
|
|
|
# xml_unescape: reverse the effects of xml_escape
|
|
|
|
sub xml_unescape($) {
|
|
|
|
my $text = shift;
|
2017-12-18 05:30:09 -07:00
|
|
|
if ($output_mode eq "man") {
|
2016-05-12 07:15:37 -06:00
|
|
|
return $text;
|
|
|
|
}
|
|
|
|
$text =~ s/\\\\\\amp;/\&/g;
|
|
|
|
$text =~ s/\\\\\\lt;/</g;
|
|
|
|
$text =~ s/\\\\\\gt;/>/g;
|
|
|
|
return $text;
|
|
|
|
}
|
|
|
|
|
2007-10-17 00:31:20 -06:00
|
|
|
# convert local escape strings to html
|
|
|
|
# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
|
|
|
|
sub local_unescape($) {
|
|
|
|
my $text = shift;
|
2017-12-18 05:30:09 -07:00
|
|
|
if ($output_mode eq "man") {
|
2007-10-17 00:31:20 -06:00
|
|
|
return $text;
|
|
|
|
}
|
|
|
|
$text =~ s/\\\\\\\\lt:/</g;
|
|
|
|
$text =~ s/\\\\\\\\gt:/>/g;
|
|
|
|
return $text;
|
|
|
|
}
|
|
|
|
|
2016-06-07 01:53:39 -06:00
|
|
|
sub map_filename($) {
|
2005-07-07 16:39:26 -06:00
|
|
|
my $file;
|
2015-09-01 16:48:49 -06:00
|
|
|
my ($orig_file) = @_;
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2005-07-07 16:39:26 -06:00
|
|
|
if (defined($ENV{'SRCTREE'})) {
|
2015-09-01 16:48:49 -06:00
|
|
|
$file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
|
2016-06-07 01:53:39 -06:00
|
|
|
} else {
|
2015-09-01 16:48:49 -06:00
|
|
|
$file = $orig_file;
|
2005-07-07 16:39:26 -06:00
|
|
|
}
|
2016-06-07 01:53:39 -06:00
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
if (defined($source_map{$file})) {
|
|
|
|
$file = $source_map{$file};
|
|
|
|
}
|
|
|
|
|
2016-06-07 01:53:39 -06:00
|
|
|
return $file;
|
|
|
|
}
|
|
|
|
|
2016-06-07 02:00:52 -06:00
|
|
|
sub process_export_file($) {
|
|
|
|
my ($orig_file) = @_;
|
|
|
|
my $file = map_filename($orig_file);
|
|
|
|
|
|
|
|
if (!open(IN,"<$file")) {
|
|
|
|
print STDERR "Error: Cannot open file $file\n";
|
|
|
|
++$errors;
|
|
|
|
return;
|
|
|
|
}
|
|
|
|
|
|
|
|
while (<IN>) {
|
|
|
|
if (/$export_symbol/) {
|
|
|
|
$function_table{$2} = 1;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
close(IN);
|
|
|
|
}
|
|
|
|
|
2016-06-07 01:53:39 -06:00
|
|
|
sub process_file($) {
|
|
|
|
my $file;
|
|
|
|
my $identifier;
|
|
|
|
my $func;
|
|
|
|
my $descr;
|
|
|
|
my $in_purpose = 0;
|
|
|
|
my $initial_section_counter = $section_counter;
|
|
|
|
my ($orig_file) = @_;
|
|
|
|
my $leading_space;
|
|
|
|
|
|
|
|
$file = map_filename($orig_file);
|
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
if (!open(IN,"<$file")) {
|
|
|
|
print STDERR "Error: Cannot open file $file\n";
|
|
|
|
++$errors;
|
|
|
|
return;
|
|
|
|
}
|
|
|
|
|
2010-02-26 14:05:47 -07:00
|
|
|
$. = 1;
|
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
$section_counter = 0;
|
|
|
|
while (<IN>) {
|
2012-10-04 18:15:05 -06:00
|
|
|
while (s/\\\s*$//) {
|
|
|
|
$_ .= <IN>;
|
|
|
|
}
|
2017-12-18 05:30:12 -07:00
|
|
|
# Replace tabs by spaces
|
|
|
|
while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
|
2016-05-26 05:56:05 -06:00
|
|
|
if ($state == STATE_NORMAL) {
|
2005-04-16 16:20:36 -06:00
|
|
|
if (/$doc_start/o) {
|
2016-05-26 05:56:05 -06:00
|
|
|
$state = STATE_NAME; # next line is always the function name
|
2006-06-25 06:48:55 -06:00
|
|
|
$in_doc_sect = 0;
|
2016-06-03 14:21:34 -06:00
|
|
|
$declaration_start_line = $. + 1;
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
2016-05-26 05:56:05 -06:00
|
|
|
} elsif ($state == STATE_NAME) {# this line is the function name (always)
|
2005-04-16 16:20:36 -06:00
|
|
|
if (/$doc_block/o) {
|
2016-05-26 05:56:05 -06:00
|
|
|
$state = STATE_DOCBLOCK;
|
2005-04-16 16:20:36 -06:00
|
|
|
$contents = "";
|
2016-06-03 14:21:34 -06:00
|
|
|
$new_start_line = $. + 1;
|
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
if ( $1 eq "" ) {
|
|
|
|
$section = $section_intro;
|
|
|
|
} else {
|
|
|
|
$section = $1;
|
|
|
|
}
|
2007-05-08 01:24:39 -06:00
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
elsif (/$doc_decl/o) {
|
|
|
|
$identifier = $1;
|
|
|
|
if (/\s*([\w\s]+?)\s*-/) {
|
|
|
|
$identifier = $1;
|
|
|
|
}
|
|
|
|
|
2016-05-26 05:56:05 -06:00
|
|
|
$state = STATE_FIELD;
|
2016-06-03 14:21:34 -06:00
|
|
|
# if there's no @param blocks need to set up default section
|
|
|
|
# here
|
2016-05-30 02:21:06 -06:00
|
|
|
$contents = "";
|
|
|
|
$section = $section_default;
|
2016-06-03 14:21:34 -06:00
|
|
|
$new_start_line = $. + 1;
|
2005-04-16 16:20:36 -06:00
|
|
|
if (/-(.*)/) {
|
2007-07-19 02:48:24 -06:00
|
|
|
# strip leading/trailing/multiple spaces
|
2007-02-10 02:46:04 -07:00
|
|
|
$descr= $1;
|
|
|
|
$descr =~ s/^\s*//;
|
|
|
|
$descr =~ s/\s*$//;
|
2012-10-04 18:15:10 -06:00
|
|
|
$descr =~ s/\s+/ /g;
|
2007-02-10 02:46:04 -07:00
|
|
|
$declaration_purpose = xml_escape($descr);
|
2009-09-17 20:26:53 -06:00
|
|
|
$in_purpose = 1;
|
2005-04-16 16:20:36 -06:00
|
|
|
} else {
|
|
|
|
$declaration_purpose = "";
|
|
|
|
}
|
2008-02-07 01:13:42 -07:00
|
|
|
|
|
|
|
if (($declaration_purpose eq "") && $verbose) {
|
2015-09-04 16:43:21 -06:00
|
|
|
print STDERR "${file}:$.: warning: missing initial short description on line:\n";
|
2008-02-07 01:13:42 -07:00
|
|
|
print STDERR $_;
|
|
|
|
++$warnings;
|
|
|
|
}
|
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
if ($identifier =~ m/^struct/) {
|
|
|
|
$decl_type = 'struct';
|
|
|
|
} elsif ($identifier =~ m/^union/) {
|
|
|
|
$decl_type = 'union';
|
|
|
|
} elsif ($identifier =~ m/^enum/) {
|
|
|
|
$decl_type = 'enum';
|
|
|
|
} elsif ($identifier =~ m/^typedef/) {
|
|
|
|
$decl_type = 'typedef';
|
|
|
|
} else {
|
|
|
|
$decl_type = 'function';
|
|
|
|
}
|
|
|
|
|
|
|
|
if ($verbose) {
|
2015-09-04 16:43:21 -06:00
|
|
|
print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
|
|
|
} else {
|
2015-09-04 16:43:21 -06:00
|
|
|
print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
|
2005-04-16 16:20:36 -06:00
|
|
|
" - I thought it was a doc line\n";
|
|
|
|
++$warnings;
|
2016-05-26 05:56:05 -06:00
|
|
|
$state = STATE_NORMAL;
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
2016-05-26 05:56:05 -06:00
|
|
|
} elsif ($state == STATE_FIELD) { # look for head: lines, and include content
|
kernel-doc: limit the "section header:" detection to a select few
kernel-doc currently identifies anything matching "section header:"
(specifically a string of word characters and spaces followed by a
colon) as a new section in the documentation comment, and renders the
section header accordingly.
Unfortunately, this turns all uses of colon into sections, mostly
unintentionally. Considering the output, erroneously creating sections
when not intended is always worse than erroneously not creating sections
when intended. For example, a line with "http://example.com" turns into
a "http" heading followed by "//example.com" in normal text style, which
is quite ugly. OTOH, "WARNING: Beware of the Leopard" is just fine even
if "WARNING" does not turn into a heading.
It is virtually impossible to change all the kernel-doc comments, either
way. The compromise is to pick the most commonly used and depended on
section headers (with variants) and accept them as section headers.
The accepted section headers are, case insensitive:
* description:
* context:
* return:
* returns:
Additionally, case sensitive:
* @return:
All of the above are commonly used in the kernel-doc comments, and will
result in worse output if not identified as section headers. Also,
kernel-doc already has some special handling for all of them, so there's
nothing particularly controversial in adding more special treatment for
them.
While at it, improve the whitespace handling surrounding section
names. Do not consider the whitespace as part of the name.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-29 02:35:28 -06:00
|
|
|
if (/$doc_sect/i) { # case insensitive for supported section names
|
2005-04-16 16:20:36 -06:00
|
|
|
$newsection = $1;
|
|
|
|
$newcontents = $2;
|
|
|
|
|
kernel-doc: limit the "section header:" detection to a select few
kernel-doc currently identifies anything matching "section header:"
(specifically a string of word characters and spaces followed by a
colon) as a new section in the documentation comment, and renders the
section header accordingly.
Unfortunately, this turns all uses of colon into sections, mostly
unintentionally. Considering the output, erroneously creating sections
when not intended is always worse than erroneously not creating sections
when intended. For example, a line with "http://example.com" turns into
a "http" heading followed by "//example.com" in normal text style, which
is quite ugly. OTOH, "WARNING: Beware of the Leopard" is just fine even
if "WARNING" does not turn into a heading.
It is virtually impossible to change all the kernel-doc comments, either
way. The compromise is to pick the most commonly used and depended on
section headers (with variants) and accept them as section headers.
The accepted section headers are, case insensitive:
* description:
* context:
* return:
* returns:
Additionally, case sensitive:
* @return:
All of the above are commonly used in the kernel-doc comments, and will
result in worse output if not identified as section headers. Also,
kernel-doc already has some special handling for all of them, so there's
nothing particularly controversial in adding more special treatment for
them.
While at it, improve the whitespace handling surrounding section
names. Do not consider the whitespace as part of the name.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-29 02:35:28 -06:00
|
|
|
# map the supported section names to the canonical names
|
|
|
|
if ($newsection =~ m/^description$/i) {
|
|
|
|
$newsection = $section_default;
|
|
|
|
} elsif ($newsection =~ m/^context$/i) {
|
|
|
|
$newsection = $section_context;
|
|
|
|
} elsif ($newsection =~ m/^returns?$/i) {
|
|
|
|
$newsection = $section_return;
|
|
|
|
} elsif ($newsection =~ m/^\@return$/) {
|
|
|
|
# special: @return is a section, not a param description
|
|
|
|
$newsection = $section_return;
|
|
|
|
}
|
|
|
|
|
2008-02-07 01:13:41 -07:00
|
|
|
if (($contents ne "") && ($contents ne "\n")) {
|
2006-06-25 06:48:55 -06:00
|
|
|
if (!$in_doc_sect && $verbose) {
|
2015-09-04 16:43:21 -06:00
|
|
|
print STDERR "${file}:$.: warning: contents before sections\n";
|
2006-06-25 06:48:55 -06:00
|
|
|
++$warnings;
|
|
|
|
}
|
2008-04-28 03:16:34 -06:00
|
|
|
dump_section($file, $section, xml_escape($contents));
|
2005-04-16 16:20:36 -06:00
|
|
|
$section = $section_default;
|
|
|
|
}
|
|
|
|
|
2006-06-25 06:48:55 -06:00
|
|
|
$in_doc_sect = 1;
|
2009-09-17 20:26:53 -06:00
|
|
|
$in_purpose = 0;
|
2005-04-16 16:20:36 -06:00
|
|
|
$contents = $newcontents;
|
2016-06-03 14:21:34 -06:00
|
|
|
$new_start_line = $.;
|
2017-12-18 05:30:12 -07:00
|
|
|
while (substr($contents, 0, 1) eq " ") {
|
2016-05-28 05:50:20 -06:00
|
|
|
$contents = substr($contents, 1);
|
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
if ($contents ne "") {
|
|
|
|
$contents .= "\n";
|
|
|
|
}
|
|
|
|
$section = $newsection;
|
2016-05-27 15:41:50 -06:00
|
|
|
$leading_space = undef;
|
2005-04-16 16:20:36 -06:00
|
|
|
} elsif (/$doc_end/) {
|
2010-03-10 16:22:02 -07:00
|
|
|
if (($contents ne "") && ($contents ne "\n")) {
|
2008-04-28 03:16:34 -06:00
|
|
|
dump_section($file, $section, xml_escape($contents));
|
2005-04-16 16:20:36 -06:00
|
|
|
$section = $section_default;
|
|
|
|
$contents = "";
|
|
|
|
}
|
2008-04-28 03:16:35 -06:00
|
|
|
# look for doc_com + <text> + doc_end:
|
|
|
|
if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
|
2015-09-04 16:43:21 -06:00
|
|
|
print STDERR "${file}:$.: warning: suspicious ending line: $_";
|
2008-04-28 03:16:35 -06:00
|
|
|
++$warnings;
|
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
$prototype = "";
|
2016-05-26 05:56:05 -06:00
|
|
|
$state = STATE_PROTO;
|
2005-04-16 16:20:36 -06:00
|
|
|
$brcount = 0;
|
2006-06-25 06:47:48 -06:00
|
|
|
# print STDERR "end of doc comment, looking for prototype\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
} elsif (/$doc_content/) {
|
|
|
|
# miguel-style comment kludge, look for blank lines after
|
|
|
|
# @parameter line to signify start of description
|
2009-09-17 20:26:53 -06:00
|
|
|
if ($1 eq "") {
|
|
|
|
if ($section =~ m/^@/ || $section eq $section_context) {
|
|
|
|
dump_section($file, $section, xml_escape($contents));
|
|
|
|
$section = $section_default;
|
|
|
|
$contents = "";
|
2016-06-03 14:21:34 -06:00
|
|
|
$new_start_line = $.;
|
2009-09-17 20:26:53 -06:00
|
|
|
} else {
|
|
|
|
$contents .= "\n";
|
|
|
|
}
|
|
|
|
$in_purpose = 0;
|
|
|
|
} elsif ($in_purpose == 1) {
|
|
|
|
# Continued declaration purpose
|
|
|
|
chomp($declaration_purpose);
|
|
|
|
$declaration_purpose .= " " . xml_escape($1);
|
2012-10-04 18:15:10 -06:00
|
|
|
$declaration_purpose =~ s/\s+/ /g;
|
2005-04-16 16:20:36 -06:00
|
|
|
} else {
|
2016-05-27 15:41:50 -06:00
|
|
|
my $cont = $1;
|
|
|
|
if ($section =~ m/^@/ || $section eq $section_context) {
|
|
|
|
if (!defined $leading_space) {
|
|
|
|
if ($cont =~ m/^(\s+)/) {
|
|
|
|
$leading_space = $1;
|
|
|
|
} else {
|
|
|
|
$leading_space = "";
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
$cont =~ s/^$leading_space//;
|
|
|
|
}
|
|
|
|
$contents .= $cont . "\n";
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
|
|
|
} else {
|
|
|
|
# i dont know - bad line? ignore.
|
2015-09-04 16:43:21 -06:00
|
|
|
print STDERR "${file}:$.: warning: bad line: $_";
|
2005-04-16 16:20:36 -06:00
|
|
|
++$warnings;
|
|
|
|
}
|
2016-05-26 05:56:05 -06:00
|
|
|
} elsif ($state == STATE_INLINE) { # scanning for inline parameters
|
2015-08-04 06:04:08 -06:00
|
|
|
# First line (state 1) needs to be a @parameter
|
2016-05-26 05:56:05 -06:00
|
|
|
if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
|
2015-08-04 06:04:08 -06:00
|
|
|
$section = $1;
|
|
|
|
$contents = $2;
|
2016-06-03 14:21:34 -06:00
|
|
|
$new_start_line = $.;
|
2015-08-04 06:04:08 -06:00
|
|
|
if ($contents ne "") {
|
2017-12-18 05:30:12 -07:00
|
|
|
while (substr($contents, 0, 1) eq " ") {
|
2015-08-04 06:04:08 -06:00
|
|
|
$contents = substr($contents, 1);
|
|
|
|
}
|
2016-05-26 13:04:06 -06:00
|
|
|
$contents .= "\n";
|
2015-08-04 06:04:08 -06:00
|
|
|
}
|
2016-05-26 05:56:05 -06:00
|
|
|
$inline_doc_state = STATE_INLINE_TEXT;
|
2015-08-04 06:04:08 -06:00
|
|
|
# Documentation block end */
|
2016-05-26 05:56:05 -06:00
|
|
|
} elsif (/$doc_inline_end/) {
|
2015-08-04 06:04:08 -06:00
|
|
|
if (($contents ne "") && ($contents ne "\n")) {
|
|
|
|
dump_section($file, $section, xml_escape($contents));
|
|
|
|
$section = $section_default;
|
|
|
|
$contents = "";
|
|
|
|
}
|
2016-05-26 05:56:05 -06:00
|
|
|
$state = STATE_PROTO;
|
|
|
|
$inline_doc_state = STATE_INLINE_NA;
|
2015-08-04 06:04:08 -06:00
|
|
|
# Regular text
|
|
|
|
} elsif (/$doc_content/) {
|
2016-05-26 05:56:05 -06:00
|
|
|
if ($inline_doc_state == STATE_INLINE_TEXT) {
|
2015-08-04 06:04:08 -06:00
|
|
|
$contents .= $1 . "\n";
|
2016-05-26 13:04:42 -06:00
|
|
|
# nuke leading blank lines
|
|
|
|
if ($contents =~ /^\s*$/) {
|
|
|
|
$contents = "";
|
|
|
|
}
|
2016-05-26 05:56:05 -06:00
|
|
|
} elsif ($inline_doc_state == STATE_INLINE_NAME) {
|
|
|
|
$inline_doc_state = STATE_INLINE_ERROR;
|
2016-07-15 02:19:30 -06:00
|
|
|
print STDERR "${file}:$.: warning: ";
|
2015-08-04 06:04:08 -06:00
|
|
|
print STDERR "Incorrect use of kernel-doc format: $_";
|
|
|
|
++$warnings;
|
|
|
|
}
|
|
|
|
}
|
2016-05-26 05:56:05 -06:00
|
|
|
} elsif ($state == STATE_PROTO) { # scanning for function '{' (end of prototype)
|
2016-11-16 08:26:16 -07:00
|
|
|
if (/$doc_inline_oneline/) {
|
|
|
|
$section = $1;
|
|
|
|
$contents = $2;
|
|
|
|
if ($contents ne "") {
|
|
|
|
$contents .= "\n";
|
|
|
|
dump_section($file, $section, xml_escape($contents));
|
|
|
|
$section = $section_default;
|
|
|
|
$contents = "";
|
|
|
|
}
|
|
|
|
} elsif (/$doc_inline_start/) {
|
2016-05-26 05:56:05 -06:00
|
|
|
$state = STATE_INLINE;
|
|
|
|
$inline_doc_state = STATE_INLINE_NAME;
|
2015-08-04 06:04:08 -06:00
|
|
|
} elsif ($decl_type eq 'function') {
|
2016-06-01 15:46:24 -06:00
|
|
|
process_proto_function($_, $file);
|
2005-04-16 16:20:36 -06:00
|
|
|
} else {
|
2016-06-01 15:46:24 -06:00
|
|
|
process_proto_type($_, $file);
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
2016-05-26 05:56:05 -06:00
|
|
|
} elsif ($state == STATE_DOCBLOCK) {
|
2016-06-01 15:46:23 -06:00
|
|
|
if (/$doc_end/)
|
2005-04-16 16:20:36 -06:00
|
|
|
{
|
2008-04-28 03:16:34 -06:00
|
|
|
dump_doc_section($file, $section, xml_escape($contents));
|
2016-05-30 02:21:06 -06:00
|
|
|
$section = $section_default;
|
2005-04-16 16:20:36 -06:00
|
|
|
$contents = "";
|
|
|
|
$function = "";
|
|
|
|
%parameterdescs = ();
|
|
|
|
%parametertypes = ();
|
|
|
|
@parameterlist = ();
|
|
|
|
%sections = ();
|
|
|
|
@sectionlist = ();
|
|
|
|
$prototype = "";
|
2016-05-26 05:56:05 -06:00
|
|
|
$state = STATE_NORMAL;
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
|
|
|
elsif (/$doc_content/)
|
|
|
|
{
|
|
|
|
if ( $1 eq "" )
|
|
|
|
{
|
|
|
|
$contents .= $blankline;
|
|
|
|
}
|
|
|
|
else
|
|
|
|
{
|
|
|
|
$contents .= $1 . "\n";
|
2006-02-01 04:06:58 -07:00
|
|
|
}
|
2007-05-08 01:24:39 -06:00
|
|
|
}
|
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
|
|
|
if ($initial_section_counter == $section_counter) {
|
2017-11-20 11:40:40 -07:00
|
|
|
if ($output_mode ne "none") {
|
|
|
|
print STDERR "${file}:1: warning: no structured comments found\n";
|
|
|
|
}
|
2016-05-29 13:19:35 -06:00
|
|
|
if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
|
2013-11-12 16:11:12 -07:00
|
|
|
print STDERR " Was looking for '$_'.\n" for keys %function_table;
|
|
|
|
}
|
2005-04-16 16:20:36 -06:00
|
|
|
}
|
|
|
|
}
|
2011-01-05 17:28:43 -07:00
|
|
|
|
|
|
|
|
|
|
|
$kernelversion = get_kernel_version();
|
|
|
|
|
|
|
|
# generate a sequence of code that will splice in highlighting information
|
|
|
|
# using the s// operator.
|
2015-11-17 08:29:49 -07:00
|
|
|
for (my $k = 0; $k < @highlights; $k++) {
|
2015-09-07 14:01:59 -06:00
|
|
|
my $pattern = $highlights[$k][0];
|
|
|
|
my $result = $highlights[$k][1];
|
|
|
|
# print STDERR "scanning pattern:$pattern, highlight:($result)\n";
|
|
|
|
$dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n";
|
2011-01-05 17:28:43 -07:00
|
|
|
}
|
|
|
|
|
|
|
|
# Read the file that maps relative names to absolute names for
|
|
|
|
# separate source and object directories and for shadow trees.
|
|
|
|
if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
|
|
|
|
my ($relname, $absname);
|
|
|
|
while(<SOURCE_MAP>) {
|
|
|
|
chop();
|
|
|
|
($relname, $absname) = (split())[0..1];
|
|
|
|
$relname =~ s:^/+::;
|
|
|
|
$source_map{$relname} = $absname;
|
|
|
|
}
|
|
|
|
close(SOURCE_MAP);
|
|
|
|
}
|
|
|
|
|
2016-06-07 02:00:52 -06:00
|
|
|
if ($output_selection == OUTPUT_EXPORTED ||
|
|
|
|
$output_selection == OUTPUT_INTERNAL) {
|
2016-06-07 02:05:53 -06:00
|
|
|
|
|
|
|
push(@export_file_list, @ARGV);
|
|
|
|
|
2016-06-07 02:00:52 -06:00
|
|
|
foreach (@export_file_list) {
|
|
|
|
chomp;
|
|
|
|
process_export_file($_);
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2011-01-05 17:28:43 -07:00
|
|
|
foreach (@ARGV) {
|
|
|
|
chomp;
|
|
|
|
process_file($_);
|
|
|
|
}
|
|
|
|
if ($verbose && $errors) {
|
|
|
|
print STDERR "$errors errors\n";
|
|
|
|
}
|
|
|
|
if ($verbose && $warnings) {
|
|
|
|
print STDERR "$warnings warnings\n";
|
|
|
|
}
|
|
|
|
|
2017-11-29 08:20:03 -07:00
|
|
|
exit($output_mode eq "none" ? 0 : $errors);
|