kernel-doc: add supported to document nested structs/
Subsystems (3)
v3 cover kernel-doc: add supported to document nested structs/
Right now, it is not possible to document nested struct and nested unions. kernel-doc simply ignore them.
Add support to document them.
Patches 1 to 6 improve kernel-doc documentation to reflect what kernel-doc currently supports and import some stuff from the old kernel-doc-nano-HOWTO.txt.
Patch 7 gets rid of the old documentation (kernel-doc-nano-HOWTO.txt).
Patch 8 gets rid of the now unused output formats for kernel-doc: since we got rid of all DocBook stuff, we should not need them anymore. The reason for dropping it (despite cleaning up), is that it doesn't make sense to invest time on adding new features for formats that aren't used anymore.
Patch 9 improves argument handling, printing script usage if an invalid argument is passed and accepting both -cmd and --cmd forms.
Patch 10 changes the default output format to ReST, as this is a way more used than man output nowadays.
Patch 11 solves an issue after ReST conversion, where tabs were not properly handled on kernel-doc tags.
Patch 12 adds support for parsing kernel-doc nested structures and unions.
Patch 13 does a cleanup, removing $nexted parameter at the routines that handle structs.
Patch 14 Improves warning output by printing the identifier where the warning occurred.
Patch 15 complements patch 12, by adding support for function definitions inside nested structures. It is needed by some media docs with use such kind of things.
Patch 16 improves nested struct handling even further, allowing it to handle cases where a nested named struct/enum with multiple identifiers added (e. g. struct { ... } foo, bar;).
Patch 17 adds documentation for nested union/struct inside w1_netlink.
The entire patch series are at my development tree, at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=nested-fix-v4b
--
v3:
- rebased on the top of docs-next branch at docs git tree;
- patches reordered to a more logical sequence;
- Change script to produce ReST format by default;
- Improve argument handling;
- Accept structs with multiple identifiers.
v2:
- solved some issues that Randy pointed;
- added patch 10 as suggested by Markus;
- Fixed some bugs on patch 9, after parsing nested structs on media subsystem;
- added patch 11 with a warning improvement fixup;
- added patch 12 in order to handle function parameters on nested structures, due to DVB demux kAPI.
v1:
- original version.
Mauro Carvalho Chehab (17):
docs: kernel-doc.rst: better describe kernel-doc arguments
docs: kernel-doc.rst: improve private members description
docs: kernel-doc.rst: improve function documentation section
docs: kernel-doc.rst: improve structs chapter
docs: kernel-doc.rst: improve typedef documentation
docs: kernel-doc.rst: add documentation about man pages
docs: get rid of kernel-doc-nano-HOWTO.txt
scripts: kernel-doc: get rid of unused output formats
scripts: kernel-doc: improve argument handling
scripts: kernel-doc: change default to ReST format
scripts: kernel-doc: replace tabs by spaces
scripts: kernel-doc: parse next structs/unions
scripts: kernel-doc: get rid of $nested parameter
scripts: kernel-doc: print the declaration name on warnings
scripts: kernel-doc: handle nested struct function arguments
scripts: kernel-doc: improve nested logic to handle multiple
identifiers
w1_netlink.h: add support for nested structs
Documentation/00-INDEX | 2 - Documentation/doc-guide/kernel-doc.rst | 360 +++++--- Documentation/kernel-doc-nano-HOWTO.txt | 322 ------- drivers/w1/w1_netlink.h | 6 +- scripts/kernel-doc | 1441 ++++--------------------------- 5 files changed, 414 insertions(+), 1717 deletions(-) delete mode 100644 Documentation/kernel-doc-nano-HOWTO.txt
Signature · 1 line
2.13.6
PATCH v3 1/17 docs: kernel-doc.rst: better describe kernel-doc arguments
Add a new section to describe kernel-doc arguments, adding examples about how identation should happen, as failing to do that causes Sphinx to do the wrong thing.
--- Documentation/doc-guide/kernel-doc.rst | 44 +++++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-)
Documentation/doc-guide/kernel-doc.rst +41 -3
@@ -112,16 +112,17 @@ Example kernel-doc function comment:: /** * foobar() - Brief description of foobar. - * @arg: Description of argument of foobar. + * @argument1: Description of parameter argument1 of foobar. + * @argument2: Description of parameter argument2 of foobar. * * Longer description of foobar. * * Return: Description of return value of foobar. */ - int foobar(int arg) + int foobar(int argument1, char *argument2) The format is similar for documentation for structures, enums, paragraphs, -etc. See the sections below for details. +etc. See the sections below for specific details of each type. The kernel-doc structure is extracted from the comments, and proper `Sphinx C Domain`_ function and type descriptions with anchors are generated for them. The
@@ -130,6 +131,43 @@ cross-references. See below for details. .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html + +Parameters and member arguments +------------------------------- + +The kernel-doc function comments describe each parameter to the function and +function typedefs or each member of struct/union, in order, with the +``@argument:`` descriptions. For each non-private member argument, one +``@argument`` definition is needed. + +The ``@argument:`` descriptions begin on the very next line following +the opening brief function description line, with no intervening blank +comment lines. + +The ``@argument:`` descriptions may span multiple lines. + +.. note:: + + If the ``@argument`` description has multiple lines, the continuation + of the description should be starting exactly at the same column as + the previous line, e. g.:: + + * @argument: some long description + * that continues on next lines + + or:: + + * @argument: + * some long description + * that continues on next lines + +If a function or typedef parameter argument is ``...`` (e. g. a variable +number of arguments), its description should be listed in kernel-doc +notation as:: + + * @...: description + + Highlights and cross-references -------------------------------
Signature · 1 line
2.13.6
PATCH v3 2/17 docs: kernel-doc.rst: improve private members description
In reply to Mauro Carvalho ChehabThe private members section can now be moved to be together with the arguments section. Move it there and add an example about the usage of public:
--- Documentation/doc-guide/kernel-doc.rst | 56 ++++++++++++++++++---------------- 1 file changed, 30 insertions(+), 26 deletions(-)
Documentation/doc-guide/kernel-doc.rst +30 -26
@@ -167,6 +167,36 @@ notation as:: * @...: description +Private members +~~~~~~~~~~~~~~~ + +Inside a struct or union description, you can use the ``private:`` and +``public:`` comment tags. Structure fields that are inside a ``private:`` +area are not listed in the generated output documentation. + +The ``private:`` and ``public:`` tags must begin immediately following a +``/*`` comment marker. They may optionally include comments between the +``:`` and the ending ``*/`` marker. + +Example:: + + /** + * struct my_struct - short description + * @a: first member + * @b: second member + * @d: fourth member + * + * Longer description + */ + struct my_struct { + int a; + int b; + /* private: internal use only */ + int c; + /* public: the next one is public */ + int d; + }; + Highlights and cross-references -------------------------------
@@ -332,32 +362,6 @@ on a line of their own, like all other kernel-doc comments:: int foobar; } -Private members -~~~~~~~~~~~~~~~ - -Inside a struct description, you can use the "private:" and "public:" comment -tags. Structure fields that are inside a "private:" area are not listed in the -generated output documentation. The "private:" and "public:" tags must begin -immediately following a ``/*`` comment marker. They may optionally include -comments between the ``:`` and the ending ``*/`` marker. - -Example:: - - /** - * struct my_struct - short description - * @a: first member - * @b: second member - * - * Longer description - */ - struct my_struct { - int a; - int b; - /* private: internal use only */ - int c; - }; - - Typedef documentation ---------------------
Signature · 1 line
2.13.6
PATCH v3 3/17 docs: kernel-doc.rst: improve function documentation section
In reply to Mauro Carvalho ChehabMove its contents to happen earlier and improve the description of return values, adding a subsection to it. Most of the contents there came from kernel-doc-nano-HOWTO.txt.
--- Documentation/doc-guide/kernel-doc.rst | 100 ++++++++++++++++++++------------- 1 file changed, 61 insertions(+), 39 deletions(-)
Documentation/doc-guide/kernel-doc.rst +61 -39
@@ -197,6 +197,67 @@ Example:: int d; }; +Function documentation +---------------------- + +The general format of a function and function-like macro kernel-doc comment is:: + + /** + * function_name() - Brief description of function. + * @arg1: Describe the first argument. + * @arg2: Describe the second argument. + * One can provide multiple line descriptions + * for arguments. + * + * A longer description, with more discussion of the function function_name() + * that might be useful to those using or modifying it. Begins with an + * empty comment line, and may include additional embedded empty + * comment lines. + * + * The longer description may have multiple paragraphs. + * + * Return: Describe the return value of foobar. + * + * The return value description can also have multiple paragraphs, and should + * be placed at the end of the comment block. + */ + +The brief description following the function name may span multiple lines, and +ends with an argument description, a blank comment line, or the end of the +comment block. + +Return values +~~~~~~~~~~~~~ + +The return value, if any, should be described in a dedicated section +named ``Return``. + +.. note:: + + #) The multi-line descriptive text you provide does *not* recognize + line breaks, so if you try to format some text nicely, as in:: + + * Return: + * 0 - OK + * -EINVAL - invalid argument + * -ENOMEM - out of memory + + this will all run together and produce:: + + Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory + + So, in order to produce the desired line breaks, you need to use a + ReST list, e. g.:: + + * Return: + * * 0 - OK to runtime suspend the device + * * -EBUSY - Device should not be runtime suspended + + #) If the descriptive text you provide has lines that begin with + some phrase followed by a colon, each of those phrases will be taken + as a new section heading, with probably won't produce the desired + effect. + Highlights and cross-references -------------------------------
@@ -269,45 +330,6 @@ cross-references. For further details, please refer to the `Sphinx C Domain`_ documentation. -Function documentation ----------------------- - -The general format of a function and function-like macro kernel-doc comment is:: - - /** - * function_name() - Brief description of function. - * @arg1: Describe the first argument. - * @arg2: Describe the second argument. - * One can provide multiple line descriptions - * for arguments. - * - * A longer description, with more discussion of the function function_name() - * that might be useful to those using or modifying it. Begins with an - * empty comment line, and may include additional embedded empty - * comment lines. - * - * The longer description may have multiple paragraphs. - * - * Return: Describe the return value of foobar. - * - * The return value description can also have multiple paragraphs, and should - * be placed at the end of the comment block. - */ - -The brief description following the function name may span multiple lines, and -ends with an ``@argument:`` description, a blank comment line, or the end of the -comment block. - -The kernel-doc function comments describe each parameter to the function, in -order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions -must begin on the very next line following the opening brief function -description line, with no intervening blank comment lines. The ``@argument:`` -descriptions may span multiple lines. The continuation lines may contain -indentation. If a function parameter is ``...`` (varargs), it should be listed -in kernel-doc notation as: ``@...:``. - -The return value, if any, should be described in a dedicated section at the end -of the comment starting with "Return:". Structure, union, and enumeration documentation -----------------------------------------------
Signature · 1 line
2.13.6
PATCH v3 4/17 docs: kernel-doc.rst: improve structs chapter
In reply to Mauro Carvalho ChehabThere is a mess on this chapter: it suggests that even enums and unions should be documented with "struct". That's not the way it should be ;-)
Fix it and move it to happen earlier.
--- Documentation/doc-guide/kernel-doc.rst | 48 +++++++++++++++++----------------- 1 file changed, 24 insertions(+), 24 deletions(-)
Documentation/doc-guide/kernel-doc.rst +24 -24
@@ -258,6 +258,30 @@ named ``Return``. as a new section heading, with probably won't produce the desired effect. +Structure, union, and enumeration documentation +----------------------------------------------- + +The general format of a struct, union, and enum kernel-doc comment is:: + + /** + * struct struct_name - Brief description. + * @argument: Description of member member_name. + * + * Description of the structure. + */ + +On the above, ``struct`` is used to mean structs. You can also use ``union`` +and ``enum`` to describe unions and enums. ``argument`` is used +to mean struct and union member names as well as enumerations in an enum. + +The brief description following the structure name may span multiple lines, and +ends with a member description, a blank comment line, or the end of the +comment block. + +The kernel-doc data structure comments describe each member of the structure, +in order, with the member descriptions. + + Highlights and cross-references -------------------------------
@@ -331,30 +355,6 @@ cross-references. For further details, please refer to the `Sphinx C Domain`_ documentation. -Structure, union, and enumeration documentation ------------------------------------------------ - -The general format of a struct, union, and enum kernel-doc comment is:: - - /** - * struct struct_name - Brief description. - * @member_name: Description of member member_name. - * - * Description of the structure. - */ - -Below, "struct" is used to mean structs, unions and enums, and "member" is used -to mean struct and union members as well as enumerations in an enum. - -The brief description following the structure name may span multiple lines, and -ends with a ``@member:`` description, a blank comment line, or the end of the -comment block. - -The kernel-doc data structure comments describe each member of the structure, in -order, with the ``@member:`` descriptions. The ``@member:`` descriptions must -begin on the very next line following the opening brief function description -line, with no intervening blank comment lines. The ``@member:`` descriptions may -span multiple lines. The continuation lines may contain indentation. In-line member documentation comments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Signature · 1 line
2.13.6
PATCH v3 5/17 docs: kernel-doc.rst: improve typedef documentation
In reply to Mauro Carvalho ChehabAdd documentation about typedefs for function prototypes and move it to happen earlier.
--- Documentation/doc-guide/kernel-doc.rst | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-)
Documentation/doc-guide/kernel-doc.rst +22 -10
@@ -282,6 +282,28 @@ The kernel-doc data structure comments describe each member of the structure, in order, with the member descriptions. +Typedef documentation +--------------------- + +The general format of a typedef kernel-doc comment is:: + + /** + * typedef type_name - Brief description. + * + * Description of the type. + */ + +Typedefs with function prototypes can also be documented:: + + /** + * typedef type_name - Brief description. + * @arg1: description of arg1 + * @arg2: description of arg2 + * + * Description of the type. + */ + typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); + Highlights and cross-references -------------------------------
@@ -384,16 +406,6 @@ on a line of their own, like all other kernel-doc comments:: int foobar; } -Typedef documentation ---------------------- - -The general format of a typedef kernel-doc comment is:: - - /** - * typedef type_name - Brief description. - * - * Description of the type. - */ Overview documentation comments -------------------------------
Signature · 1 line
2.13.6
PATCH v3 6/17 docs: kernel-doc.rst: add documentation about man pages
In reply to Mauro Carvalho Chehabkernel-doc-nano-HOWTO.txt has a chapter about man pages production. While we don't have a working "make manpages" target, add it.
--- Documentation/doc-guide/kernel-doc.rst | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+)
Documentation/doc-guide/kernel-doc.rst +34 -0
@@ -452,3 +452,37 @@ file. Data structures visible in kernel include files should also be documented using kernel-doc formatted comments. + +How to use kernel-doc to generate man pages +------------------------------------------- + +If you just want to use kernel-doc to generate man pages you can do this +from the Kernel git tree:: + + $ scripts/kernel-doc -man $(git grep -l '/\*\*' |grep -v Documentation/) | ./split-man.pl /tmp/man + +Using the small ``split-man.pl`` script below:: + + + #!/usr/bin/perl + + if ($#ARGV < 0) { + die "where do I put the results?\n"; + } + + mkdir $ARGV[0],0777; + $state = 0; + while (<STDIN>) { + if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) { + if ($state == 1) { close OUT } + $state = 1; + $fn = "$ARGV[0]/$1.9"; + print STDERR "Creating $fn\n"; + open OUT, ">$fn" or die "can't open $fn: $!\n"; + print OUT $_; + } elsif ($state != 0) { + print OUT $_; + } + } + + close OUT;
Signature · 1 line
2.13.6
PATCH v3 7/17 docs: get rid of kernel-doc-nano-HOWTO.txt
In reply to Mauro Carvalho ChehabEverything there is already described at Documentation/doc-guide/kernel-doc.rst. So, there's no reason why to keep it anymore.
--- Documentation/00-INDEX | 2 - Documentation/kernel-doc-nano-HOWTO.txt | 322 -------------------------------- scripts/kernel-doc | 2 +- 3 files changed, 1 insertion(+), 325 deletions(-) delete mode 100644 Documentation/kernel-doc-nano-HOWTO.txt
Documentation/00-INDEX +0 -2
@@ -228,8 +228,6 @@ isdn/ - directory with info on the Linux ISDN support, and supported cards. kbuild/ - directory with info about the kernel build process. -kernel-doc-nano-HOWTO.txt - - outdated info about kernel-doc documentation. kdump/ - directory with mini HowTo on getting the crash dump code to work. doc-guide/
Documentation/kernel-doc-nano-HOWTO.txt deleted +0 -322
322 lines not on this page · raw message
scripts/kernel-doc +1 -1
@@ -48,7 +48,7 @@ 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 -Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax. +Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax. Output format selection (mutually exclusive): -docbook Output DocBook format.
Signature · 1 line
2.13.6
PATCH v3 8/17 scripts: kernel-doc: get rid of unused output formats
In reply to Mauro Carvalho ChehabSince there isn't any docbook code anymore upstream, we can get rid of several output formats:
- docbook/xml, html, html5 and list formats were used by the old build system;
- As ReST is text, there's not much sense on outputting on a different text format.
After this patch, only man and rst output formats are supported.
--- scripts/kernel-doc | 1182 +--------------------------------------------------- 1 file changed, 4 insertions(+), 1178 deletions(-)
scripts/kernel-doc +4 -1178
@@ -51,13 +51,8 @@ The documentation comments are identified by "/**" opening comment mark. See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax. Output format selection (mutually exclusive): - -docbook Output DocBook format. - -html Output HTML format. - -html5 Output HTML5 format. - -list Output symbol list format. This is for use by docproc. -man Output troff manual page format. This is the default. -rst Output reStructuredText format. - -text Output plain text format. Output selection (mutually exclusive): -export Only output documentation for symbols that have been
@@ -224,84 +219,11 @@ my $type_typedef = '\&(typedef\s*([_\w]+))'; my $type_union = '\&(union\s*([_\w]+))'; my $type_member = '\&([_\w]+)(\.|->)([_\w]+)'; my $type_fallback = '\&([_\w]+)'; -my $type_enum_xml = '\&(enum\s*([_\w]+))'; -my $type_struct_xml = '\&(struct\s*([_\w]+))'; -my $type_typedef_xml = '\&(typedef\s*([_\w]+))'; -my $type_union_xml = '\&(union\s*([_\w]+))'; -my $type_member_xml = '\&([_\w]+)(\.|-\>)([_\w]+)'; -my $type_fallback_xml = '\&([_\w]+)'; my $type_member_func = $type_member . '\(\)'; # Output conversion substitutions. # One for each output format -# these work fairly well -my @highlights_html = ( - [$type_constant, "<i>\$1</i>"], - [$type_constant2, "<i>\$1</i>"], - [$type_func, "<b>\$1</b>"], - [$type_enum_xml, "<i>\$1</i>"], - [$type_struct_xml, "<i>\$1</i>"], - [$type_typedef_xml, "<i>\$1</i>"], - [$type_union_xml, "<i>\$1</i>"], - [$type_env, "<b><i>\$1</i></b>"], - [$type_param, "<tt><b>\$1</b></tt>"], - [$type_member_xml, "<tt><i>\$1</i>\$2\$3</tt>"], - [$type_fallback_xml, "<i>\$1</i>"] - ); -my $local_lt = "\\\\\\\\lt:"; -my $local_gt = "\\\\\\\\gt:"; -my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>" - -# html version 5 -my @highlights_html5 = ( - [$type_constant, "<span class=\"const\">\$1</span>"], - [$type_constant2, "<span class=\"const\">\$1</span>"], - [$type_func, "<span class=\"func\">\$1</span>"], - [$type_enum_xml, "<span class=\"enum\">\$1</span>"], - [$type_struct_xml, "<span class=\"struct\">\$1</span>"], - [$type_typedef_xml, "<span class=\"typedef\">\$1</span>"], - [$type_union_xml, "<span class=\"union\">\$1</span>"], - [$type_env, "<span class=\"env\">\$1</span>"], - [$type_param, "<span class=\"param\">\$1</span>]"], - [$type_member_xml, "<span class=\"literal\"><span class=\"struct\">\$1</span>\$2<span class=\"member\">\$3</span></span>"], - [$type_fallback_xml, "<span class=\"struct\">\$1</span>"] - ); -my $blankline_html5 = $local_lt . "br /" . $local_gt; - -# XML, docbook format -my @highlights_xml = ( - ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"], - [$type_constant, "<constant>\$1</constant>"], - [$type_constant2, "<constant>\$1</constant>"], - [$type_enum_xml, "<type>\$1</type>"], - [$type_struct_xml, "<structname>\$1</structname>"], - [$type_typedef_xml, "<type>\$1</type>"], - [$type_union_xml, "<structname>\$1</structname>"], - [$type_param, "<parameter>\$1</parameter>"], - [$type_func, "<function>\$1</function>"], - [$type_env, "<envar>\$1</envar>"], - [$type_member_xml, "<literal><structname>\$1</structname>\$2<structfield>\$3</structfield></literal>"], - [$type_fallback_xml, "<structname>\$1</structname>"] - ); -my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n"; - -# gnome, docbook format -my @highlights_gnome = ( - [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"], - [$type_constant2, "<replaceable class=\"option\">\$1</replaceable>"], - [$type_func, "<function>\$1</function>"], - [$type_enum, "<type>\$1</type>"], - [$type_struct, "<structname>\$1</structname>"], - [$type_typedef, "<type>\$1</type>"], - [$type_union, "<structname>\$1</structname>"], - [$type_env, "<envar>\$1</envar>"], - [$type_param, "<parameter>\$1</parameter>" ], - [$type_member, "<literal><structname>\$1</structname>\$2<structfield>\$3</structfield></literal>"], - [$type_fallback, "<structname>\$1</structname>"] - ); -my $blankline_gnome = "</para><para>\n"; - # these are pretty rough my @highlights_man = ( [$type_constant, "\$1"],
@@ -317,21 +239,6 @@ my @highlights_man = ( ); my $blankline_man = ""; -# text-mode -my @highlights_text = ( - [$type_constant, "\$1"], - [$type_constant2, "\$1"], - [$type_func, "\$1"], - [$type_enum, "\$1"], - [$type_struct, "\$1"], - [$type_typedef, "\$1"], - [$type_union, "\$1"], - [$type_param, "\$1"], - [$type_member, "\$1\$2\$3"], - [$type_fallback, "\$1"] - ); -my $blankline_text = ""; - # rst-mode my @highlights_rst = ( [$type_constant, "``\$1``"],
@@ -351,21 +258,6 @@ my @highlights_rst = ( ); my $blankline_rst = "\n"; -# list mode -my @highlights_list = ( - [$type_constant, "\$1"], - [$type_constant2, "\$1"], - [$type_func, "\$1"], - [$type_enum, "\$1"], - [$type_struct, "\$1"], - [$type_typedef, "\$1"], - [$type_union, "\$1"], - [$type_param, "\$1"], - [$type_member, "\$1"], - [$type_fallback, "\$1"] - ); -my $blankline_list = ""; - # read arguments if ($#ARGV == -1) { usage();
@@ -500,38 +392,14 @@ reset_state(); while ($ARGV[0] =~ m/^-(.*)/) { my $cmd = shift @ARGV; - if ($cmd eq "-html") { - $output_mode = "html"; - @highlights = @highlights_html; - $blankline = $blankline_html; - } elsif ($cmd eq "-html5") { - $output_mode = "html5"; - @highlights = @highlights_html5; - $blankline = $blankline_html5; - } elsif ($cmd eq "-man") { + if ($cmd eq "-man") { $output_mode = "man"; @highlights = @highlights_man; $blankline = $blankline_man; - } elsif ($cmd eq "-text") { - $output_mode = "text"; - @highlights = @highlights_text; - $blankline = $blankline_text; } elsif ($cmd eq "-rst") { $output_mode = "rst"; @highlights = @highlights_rst; $blankline = $blankline_rst; - } elsif ($cmd eq "-docbook") { - $output_mode = "xml"; - @highlights = @highlights_xml; - $blankline = $blankline_xml; - } elsif ($cmd eq "-list") { - $output_mode = "list"; - @highlights = @highlights_list; - $blankline = $blankline_list; - } elsif ($cmd eq "-gnome") { - $output_mode = "gnome"; - @highlights = @highlights_gnome; - $blankline = $blankline_gnome; } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document $modulename = shift @ARGV; } elsif ($cmd eq "-function") { # to only output specific functions
@@ -667,22 +535,11 @@ sub output_highlight { # confess "output_highlight got called with no args?\n"; # } - if ($output_mode eq "html" || $output_mode eq "html5" || - $output_mode eq "xml") { - $contents = local_unescape($contents); - # convert data read & converted thru xml_escape() into &xyz; format: - $contents =~ s/\\\\\\/\&/g; - } # print STDERR "contents b4:$contents\n"; eval $dohighlight; die $@ if $@; # print STDERR "contents af:$contents\n"; -# strip whitespaces when generating html5 - if ($output_mode eq "html5") { - $contents =~ s/^\s+//; - $contents =~ s/\s+$//; - } foreach $line (split "\n", $contents) { if (! $output_preformatted) { $line =~ s/^\s*//;
@@ -703,817 +560,6 @@ sub output_highlight { } } -# output sections in html -sub output_section_html(%) { - my %args = %{$_[0]}; - my $section; - - foreach $section (@{$args{'sectionlist'}}) { - print "<h3>$section</h3>\n"; - print "<blockquote>\n"; - output_highlight($args{'sections'}{$section}); - print "</blockquote>\n"; - } -} - -# output enum in html -sub output_enum_html(%) { - my %args = %{$_[0]}; - my ($parameter); - my $count; - print "<h2>enum " . $args{'enum'} . "</h2>\n"; - - print "<b>enum " . $args{'enum'} . "</b> {<br>\n"; - $count = 0; - foreach $parameter (@{$args{'parameterlist'}}) { - print " <b>" . $parameter . "</b>"; - if ($count != $#{$args{'parameterlist'}}) { - $count++; - print ",\n"; - } - print "<br>"; - } - print "};<br>\n"; - - print "<h3>Constants</h3>\n"; - print "<dl>\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - print "<dt><b>" . $parameter . "</b>\n"; - print "<dd>"; - output_highlight($args{'parameterdescs'}{$parameter}); - } - print "</dl>\n"; - output_section_html(@_); - print "<hr>\n"; -} - -# output typedef in html -sub output_typedef_html(%) { - my %args = %{$_[0]}; - my ($parameter); - my $count; - print "<h2>typedef " . $args{'typedef'} . "</h2>\n"; - - print "<b>typedef " . $args{'typedef'} . "</b>\n"; - output_section_html(@_); - print "<hr>\n"; -} - -# output struct in html -sub output_struct_html(%) { - my %args = %{$_[0]}; - my ($parameter); - - print "<h2>" . $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "</h2>\n"; - print "<b>" . $args{'type'} . " " . $args{'struct'} . "</b> {<br>\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - if ($parameter =~ /^#/) { - print "$parameter<br>\n"; - next; - } - my $parameter_name = $parameter; - $parameter_name =~ s/\[.*//; - - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; - $type = $args{'parametertypes'}{$parameter}; - if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { - # pointer-to-function - print " <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n"; - } elsif ($type =~ m/^(.*?)\s*(:.*)/) { - # bitfield - print " <i>$1</i> <b>$parameter</b>$2;<br>\n"; - } else { - print " <i>$type</i> <b>$parameter</b>;<br>\n"; - } - } - print "};<br>\n"; - - print "<h3>Members</h3>\n"; - print "<dl>\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - ($parameter =~ /^#/) && next; - - my $parameter_name = $parameter; - $parameter_name =~ s/\[.*//; - - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; - print "<dt><b>" . $parameter . "</b>\n"; - print "<dd>"; - output_highlight($args{'parameterdescs'}{$parameter_name}); - } - print "</dl>\n"; - output_section_html(@_); - print "<hr>\n"; -} - -# output function in html -sub output_function_html(%) { - my %args = %{$_[0]}; - my ($parameter, $section); - my $count; - - print "<h2>" . $args{'function'} . " - " . $args{'purpose'} . "</h2>\n"; - print "<i>" . $args{'functiontype'} . "</i>\n"; - print "<b>" . $args{'function'} . "</b>\n"; - print "("; - $count = 0; - foreach $parameter (@{$args{'parameterlist'}}) { - $type = $args{'parametertypes'}{$parameter}; - if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { - # pointer-to-function - print "<i>$1</i><b>$parameter</b>) <i>($2)</i>"; - } else { - print "<i>" . $type . "</i> <b>" . $parameter . "</b>"; - } - if ($count != $#{$args{'parameterlist'}}) { - $count++; - print ",\n"; - } - } - print ")\n"; - - print "<h3>Arguments</h3>\n"; - print "<dl>\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - my $parameter_name = $parameter; - $parameter_name =~ s/\[.*//; - - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; - print "<dt><b>" . $parameter . "</b>\n"; - print "<dd>"; - output_highlight($args{'parameterdescs'}{$parameter_name}); - } - print "</dl>\n"; - output_section_html(@_); - print "<hr>\n"; -} - -# output DOC: block header in html -sub output_blockhead_html(%) { - my %args = %{$_[0]}; - my ($parameter, $section); - my $count; - - foreach $section (@{$args{'sectionlist'}}) { - print "<h3>$section</h3>\n"; - print "<ul>\n"; - output_highlight($args{'sections'}{$section}); - print "</ul>\n"; - } - print "<hr>\n"; -} - -# output sections in html5 -sub output_section_html5(%) { - my %args = %{$_[0]}; - my $section; - - foreach $section (@{$args{'sectionlist'}}) { - print "<section>\n"; - print "<h1>$section</h1>\n"; - print "<p>\n"; - output_highlight($args{'sections'}{$section}); - print "</p>\n"; - print "</section>\n"; - } -} - -# output enum in html5 -sub output_enum_html5(%) { - my %args = %{$_[0]}; - my ($parameter); - my $count; - my $html5id; - - $html5id = $args{'enum'}; - $html5id =~ s/[^a-zA-Z0-9\-]+/_/g; - print "<article class=\"enum\" id=\"enum:". $html5id . "\">"; - print "<h1>enum " . $args{'enum'} . "</h1>\n"; - print "<ol class=\"code\">\n"; - print "<li>"; - print "<span class=\"keyword\">enum</span> "; - print "<span class=\"identifier\">" . $args{'enum'} . "</span> {"; - print "</li>\n"; - $count = 0; - foreach $parameter (@{$args{'parameterlist'}}) { - print "<li class=\"indent\">"; - print "<span class=\"param\">" . $parameter . "</span>"; - if ($count != $#{$args{'parameterlist'}}) { - $count++; - print ","; - } - print "</li>\n"; - } - print "<li>};</li>\n"; - print "</ol>\n"; - - print "<section>\n"; - print "<h1>Constants</h1>\n"; - print "<dl>\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - print "<dt>" . $parameter . "</dt>\n"; - print "<dd>"; - output_highlight($args{'parameterdescs'}{$parameter}); - print "</dd>\n"; - } - print "</dl>\n"; - print "</section>\n"; - output_section_html5(@_); - print "</article>\n"; -} - -# output typedef in html5 -sub output_typedef_html5(%) { - my %args = %{$_[0]}; - my ($parameter); - my $count; - my $html5id; - - $html5id = $args{'typedef'}; - $html5id =~ s/[^a-zA-Z0-9\-]+/_/g; - print "<article class=\"typedef\" id=\"typedef:" . $html5id . "\">\n"; - print "<h1>typedef " . $args{'typedef'} . "</h1>\n"; - - print "<ol class=\"code\">\n"; - print "<li>"; - print "<span class=\"keyword\">typedef</span> "; - print "<span class=\"identifier\">" . $args{'typedef'} . "</span>"; - print "</li>\n"; - print "</ol>\n"; - output_section_html5(@_); - print "</article>\n"; -} - -# output struct in html5 -sub output_struct_html5(%) { - my %args = %{$_[0]}; - my ($parameter); - my $html5id; - - $html5id = $args{'struct'}; - $html5id =~ s/[^a-zA-Z0-9\-]+/_/g; - print "<article class=\"struct\" id=\"struct:" . $html5id . "\">\n"; - print "<hgroup>\n"; - print "<h1>" . $args{'type'} . " " . $args{'struct'} . "</h1>"; - print "<h2>". $args{'purpose'} . "</h2>\n"; - print "</hgroup>\n"; - print "<ol class=\"code\">\n"; - print "<li>"; - print "<span class=\"type\">" . $args{'type'} . "</span> "; - print "<span class=\"identifier\">" . $args{'struct'} . "</span> {"; - print "</li>\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - print "<li class=\"indent\">"; - if ($parameter =~ /^#/) { - print "<span class=\"param\">" . $parameter ."</span>\n"; - print "</li>\n"; - next; - } - my $parameter_name = $parameter; - $parameter_name =~ s/\[.*//; - - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; - $type = $args{'parametertypes'}{$parameter}; - if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { - # pointer-to-function - print "<span class=\"type\">$1</span> "; - print "<span class=\"param\">$parameter</span>"; - print "<span class=\"type\">)</span> "; - print "(<span class=\"args\">$2</span>);"; - } elsif ($type =~ m/^(.*?)\s*(:.*)/) { - # bitfield - print "<span class=\"type\">$1</span> "; - print "<span class=\"param\">$parameter</span>"; - print "<span class=\"bits\">$2</span>;"; - } else { - print "<span class=\"type\">$type</span> "; - print "<span class=\"param\">$parameter</span>;"; - } - print "</li>\n"; - } - print "<li>};</li>\n"; - print "</ol>\n"; - - print "<section>\n"; - print "<h1>Members</h1>\n"; - print "<dl>\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - ($parameter =~ /^#/) && next; - - my $parameter_name = $parameter; - $parameter_name =~ s/\[.*//; - - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; - print "<dt>" . $parameter . "</dt>\n"; - print "<dd>"; - output_highlight($args{'parameterdescs'}{$parameter_name}); - print "</dd>\n"; - } - print "</dl>\n"; - print "</section>\n"; - output_section_html5(@_); - print "</article>\n"; -} - -# output function in html5 -sub output_function_html5(%) { - my %args = %{$_[0]}; - my ($parameter, $section); - my $count; - my $html5id; - - $html5id = $args{'function'}; - $html5id =~ s/[^a-zA-Z0-9\-]+/_/g; - print "<article class=\"function\" id=\"func:". $html5id . "\">\n"; - print "<hgroup>\n"; - print "<h1>" . $args{'function'} . "</h1>"; - print "<h2>" . $args{'purpose'} . "</h2>\n"; - print "</hgroup>\n"; - print "<ol class=\"code\">\n"; - print "<li>"; - print "<span class=\"type\">" . $args{'functiontype'} . "</span> "; - print "<span class=\"identifier\">" . $args{'function'} . "</span> ("; - print "</li>"; - $count = 0; - foreach $parameter (@{$args{'parameterlist'}}) { - print "<li class=\"indent\">"; - $type = $args{'parametertypes'}{$parameter}; - if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { - # pointer-to-function - print "<span class=\"type\">$1</span> "; - print "<span class=\"param\">$parameter</span>"; - print "<span class=\"type\">)</span> "; - print "(<span class=\"args\">$2</span>)"; - } else { - print "<span class=\"type\">$type</span> "; - print "<span class=\"param\">$parameter</span>"; - } - if ($count != $#{$args{'parameterlist'}}) { - $count++; - print ","; - } - print "</li>\n"; - } - print "<li>)</li>\n"; - print "</ol>\n"; - - print "<section>\n"; - print "<h1>Arguments</h1>\n"; - print "<p>\n"; - print "<dl>\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - my $parameter_name = $parameter; - $parameter_name =~ s/\[.*//; - - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; - print "<dt>" . $parameter . "</dt>\n"; - print "<dd>"; - output_highlight($args{'parameterdescs'}{$parameter_name}); - print "</dd>\n"; - } - print "</dl>\n"; - print "</section>\n"; - output_section_html5(@_); - print "</article>\n"; -} - -# output DOC: block header in html5 -sub output_blockhead_html5(%) { - my %args = %{$_[0]}; - my ($parameter, $section); - my $count; - my $html5id; - - foreach $section (@{$args{'sectionlist'}}) { - $html5id = $section; - $html5id =~ s/[^a-zA-Z0-9\-]+/_/g; - print "<article class=\"doc\" id=\"doc:". $html5id . "\">\n"; - print "<h1>$section</h1>\n"; - print "<p>\n"; - output_highlight($args{'sections'}{$section}); - print "</p>\n"; - } - print "</article>\n"; -} - -sub output_section_xml(%) { - my %args = %{$_[0]}; - my $section; - # print out each section - $lineprefix=" "; - foreach $section (@{$args{'sectionlist'}}) { - print "<refsect1>\n"; - print "<title>$section</title>\n"; - if ($section =~ m/EXAMPLE/i) { - print "<informalexample><programlisting>\n"; - $output_preformatted = 1; - } else { - print "<para>\n"; - } - output_highlight($args{'sections'}{$section}); - $output_preformatted = 0; - if ($section =~ m/EXAMPLE/i) { - print "</programlisting></informalexample>\n"; - } else { - print "</para>\n"; - } - print "</refsect1>\n"; - } -} - -# output function in XML DocBook -sub output_function_xml(%) { - my %args = %{$_[0]}; - my ($parameter, $section); - my $count; - my $id; - - $id = "API-" . $args{'function'}; - $id =~ s/[^A-Za-z0-9]/-/g; - - print "<refentry id=\"$id\">\n"; - print "<refentryinfo>\n"; - print " <title>LINUX</title>\n"; - print " <productname>Kernel Hackers Manual</productname>\n"; - print " <date>$man_date</date>\n"; - print "</refentryinfo>\n"; - print "<refmeta>\n"; - print " <refentrytitle><phrase>" . $args{'function'} . "</phrase></refentrytitle>\n"; - print " <manvolnum>9</manvolnum>\n"; - print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n"; - print "</refmeta>\n"; - print "<refnamediv>\n"; - print " <refname>" . $args{'function'} . "</refname>\n"; - print " <refpurpose>\n"; - print " "; - output_highlight ($args{'purpose'}); - print " </refpurpose>\n"; - print "</refnamediv>\n"; - - print "<refsynopsisdiv>\n"; - print " <title>Synopsis</title>\n"; - print " <funcsynopsis><funcprototype>\n"; - print " <funcdef>" . $args{'functiontype'} . " "; - print "<function>" . $args{'function'} . " </function></funcdef>\n"; - - $count = 0; - if ($#{$args{'parameterlist'}} >= 0) { - foreach $parameter (@{$args{'parameterlist'}}) { - $type = $args{'parametertypes'}{$parameter}; - if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { - # pointer-to-function - print " <paramdef>$1<parameter>$parameter</parameter>)\n"; - print " <funcparams>$2</funcparams></paramdef>\n"; - } else { - print " <paramdef>" . $type; - print " <parameter>$parameter</parameter></paramdef>\n"; - } - } - } else { - print " <void/>\n"; - } - print " </funcprototype></funcsynopsis>\n"; - print "</refsynopsisdiv>\n"; - - # print parameters - print "<refsect1>\n <title>Arguments</title>\n"; - if ($#{$args{'parameterlist'}} >= 0) { - print " <variablelist>\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - my $parameter_name = $parameter; - $parameter_name =~ s/\[.*//; - $type = $args{'parametertypes'}{$parameter}; - - print " <varlistentry>\n <term><parameter>$type $parameter</parameter></term>\n"; - print " <listitem>\n <para>\n"; - $lineprefix=" "; - output_highlight($args{'parameterdescs'}{$parameter_name}); - print " </para>\n </listitem>\n </varlistentry>\n"; - } - print " </variablelist>\n"; - } else { - print " <para>\n None\n </para>\n"; - } - print "</refsect1>\n"; - - output_section_xml(@_); - print "</refentry>\n\n"; -} - -# output struct in XML DocBook -sub output_struct_xml(%) { - my %args = %{$_[0]}; - my ($parameter, $section); - my $id; - - $id = "API-struct-" . $args{'struct'}; - $id =~ s/[^A-Za-z0-9]/-/g; - - print "<refentry id=\"$id\">\n"; - print "<refentryinfo>\n"; - print " <title>LINUX</title>\n"; - print " <productname>Kernel Hackers Manual</productname>\n"; - print " <date>$man_date</date>\n"; - print "</refentryinfo>\n"; - print "<refmeta>\n"; - print " <refentrytitle><phrase>" . $args{'type'} . " " . $args{'struct'} . "</phrase></refentrytitle>\n"; - print " <manvolnum>9</manvolnum>\n"; - print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n"; - print "</refmeta>\n"; - print "<refnamediv>\n"; - print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n"; - print " <refpurpose>\n"; - print " "; - output_highlight ($args{'purpose'}); - print " </refpurpose>\n"; - print "</refnamediv>\n"; - - print "<refsynopsisdiv>\n"; - print " <title>Synopsis</title>\n"; - print " <programlisting>\n"; - print $args{'type'} . " " . $args{'struct'} . " {\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - if ($parameter =~ /^#/) { - my $prm = $parameter; - # convert data read & converted thru xml_escape() into &xyz; format: - # This allows us to have #define macros interspersed in a struct. - $prm =~ s/\\\\\\/\&/g; - print "$prm\n"; - next; - } - - my $parameter_name = $parameter; - $parameter_name =~ s/\[.*//; - - defined($args{'parameterdescs'}{$parameter_name}) || next; - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; - $type = $args{'parametertypes'}{$parameter}; - if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { - # pointer-to-function - print " $1 $parameter) ($2);\n"; - } elsif ($type =~ m/^(.*?)\s*(:.*)/) { - # bitfield - print " $1 $parameter$2;\n"; - } else { - print " " . $type . " " . $parameter . ";\n"; - } - } - print "};"; - print " </programlisting>\n"; - print "</refsynopsisdiv>\n"; - - print " <refsect1>\n"; - print " <title>Members</title>\n"; - - if ($#{$args{'parameterlist'}} >= 0) { - print " <variablelist>\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - ($parameter =~ /^#/) && next; - - my $parameter_name = $parameter; - $parameter_name =~ s/\[.*//; - - defined($args{'parameterdescs'}{$parameter_name}) || next; - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; - $type = $args{'parametertypes'}{$parameter}; - print " <varlistentry>"; - print " <term><literal>$type $parameter</literal></term>\n"; - print " <listitem><para>\n"; - output_highlight($args{'parameterdescs'}{$parameter_name}); - print " </para></listitem>\n"; - print " </varlistentry>\n"; - } - print " </variablelist>\n"; - } else { - print " <para>\n None\n </para>\n"; - } - print " </refsect1>\n"; - - output_section_xml(@_); - - print "</refentry>\n\n"; -} - -# output enum in XML DocBook -sub output_enum_xml(%) { - my %args = %{$_[0]}; - my ($parameter, $section); - my $count; - my $id; - - $id = "API-enum-" . $args{'enum'}; - $id =~ s/[^A-Za-z0-9]/-/g; - - print "<refentry id=\"$id\">\n"; - print "<refentryinfo>\n"; - print " <title>LINUX</title>\n"; - print " <productname>Kernel Hackers Manual</productname>\n"; - print " <date>$man_date</date>\n"; - print "</refentryinfo>\n"; - print "<refmeta>\n"; - print " <refentrytitle><phrase>enum " . $args{'enum'} . "</phrase></refentrytitle>\n"; - print " <manvolnum>9</manvolnum>\n"; - print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n"; - print "</refmeta>\n"; - print "<refnamediv>\n"; - print " <refname>enum " . $args{'enum'} . "</refname>\n"; - print " <refpurpose>\n"; - print " "; - output_highlight ($args{'purpose'}); - print " </refpurpose>\n"; - print "</refnamediv>\n"; - - print "<refsynopsisdiv>\n"; - print " <title>Synopsis</title>\n"; - print " <programlisting>\n"; - print "enum " . $args{'enum'} . " {\n"; - $count = 0; - foreach $parameter (@{$args{'parameterlist'}}) { - print " $parameter"; - if ($count != $#{$args{'parameterlist'}}) { - $count++; - print ","; - } - print "\n"; - } - print "};"; - print " </programlisting>\n"; - print "</refsynopsisdiv>\n"; - - print "<refsect1>\n"; - print " <title>Constants</title>\n"; - print " <variablelist>\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - my $parameter_name = $parameter; - $parameter_name =~ s/\[.*//; - - print " <varlistentry>"; - print " <term>$parameter</term>\n"; - print " <listitem><para>\n"; - output_highlight($args{'parameterdescs'}{$parameter_name}); - print " </para></listitem>\n"; - print " </varlistentry>\n"; - } - print " </variablelist>\n"; - print "</refsect1>\n"; - - output_section_xml(@_); - - print "</refentry>\n\n"; -} - -# output typedef in XML DocBook -sub output_typedef_xml(%) { - my %args = %{$_[0]}; - my ($parameter, $section); - my $id; - - $id = "API-typedef-" . $args{'typedef'}; - $id =~ s/[^A-Za-z0-9]/-/g; - - print "<refentry id=\"$id\">\n"; - print "<refentryinfo>\n"; - print " <title>LINUX</title>\n"; - print " <productname>Kernel Hackers Manual</productname>\n"; - print " <date>$man_date</date>\n"; - print "</refentryinfo>\n"; - print "<refmeta>\n"; - print " <refentrytitle><phrase>typedef " . $args{'typedef'} . "</phrase></refentrytitle>\n"; - print " <manvolnum>9</manvolnum>\n"; - print "</refmeta>\n"; - print "<refnamediv>\n"; - print " <refname>typedef " . $args{'typedef'} . "</refname>\n"; - print " <refpurpose>\n"; - print " "; - output_highlight ($args{'purpose'}); - print " </refpurpose>\n"; - print "</refnamediv>\n"; - - print "<refsynopsisdiv>\n"; - print " <title>Synopsis</title>\n"; - print " <synopsis>typedef " . $args{'typedef'} . ";</synopsis>\n"; - print "</refsynopsisdiv>\n"; - - output_section_xml(@_); - - print "</refentry>\n\n"; -} - -# output in XML DocBook -sub output_blockhead_xml(%) { - my %args = %{$_[0]}; - my ($parameter, $section); - my $count; - - my $id = $args{'module'}; - $id =~ s/[^A-Za-z0-9]/-/g; - - # print out each section - $lineprefix=" "; - foreach $section (@{$args{'sectionlist'}}) { - if (!$args{'content-only'}) { - print "<refsect1>\n <title>$section</title>\n"; - } - if ($section =~ m/EXAMPLE/i) { - print "<example><para>\n"; - $output_preformatted = 1; - } else { - print "<para>\n"; - } - output_highlight($args{'sections'}{$section}); - $output_preformatted = 0; - if ($section =~ m/EXAMPLE/i) { - print "</para></example>\n"; - } else { - print "</para>"; - } - if (!$args{'content-only'}) { - print "\n</refsect1>\n"; - } - } - - print "\n\n"; -} - -# output in XML DocBook -sub output_function_gnome { - my %args = %{$_[0]}; - my ($parameter, $section); - my $count; - my $id; - - $id = $args{'module'} . "-" . $args{'function'}; - $id =~ s/[^A-Za-z0-9]/-/g; - - print "<sect2>\n"; - print " <title id=\"$id\">" . $args{'function'} . "</title>\n"; - - print " <funcsynopsis>\n"; - print " <funcdef>" . $args{'functiontype'} . " "; - print "<function>" . $args{'function'} . " "; - print "</function></funcdef>\n"; - - $count = 0; - if ($#{$args{'parameterlist'}} >= 0) { - foreach $parameter (@{$args{'parameterlist'}}) { - $type = $args{'parametertypes'}{$parameter}; - if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { - # pointer-to-function - print " <paramdef>$1 <parameter>$parameter</parameter>)\n"; - print " <funcparams>$2</funcparams></paramdef>\n"; - } else { - print " <paramdef>" . $type; - print " <parameter>$parameter</parameter></paramdef>\n"; - } - } - } else { - print " <void>\n"; - } - print " </funcsynopsis>\n"; - if ($#{$args{'parameterlist'}} >= 0) { - print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n"; - print "<tgroup cols=\"2\">\n"; - print "<colspec colwidth=\"2*\">\n"; - print "<colspec colwidth=\"8*\">\n"; - print "<tbody>\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - my $parameter_name = $parameter; - $parameter_name =~ s/\[.*//; - - print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n"; - print " <entry>\n"; - $lineprefix=" "; - output_highlight($args{'parameterdescs'}{$parameter_name}); - print " </entry></row>\n"; - } - print " </tbody></tgroup></informaltable>\n"; - } else { - print " <para>\n None\n </para>\n"; - } - - # print out each section - $lineprefix=" "; - foreach $section (@{$args{'sectionlist'}}) { - print "<simplesect>\n <title>$section</title>\n"; - if ($section =~ m/EXAMPLE/i) { - print "<example><programlisting>\n"; - $output_preformatted = 1; - } else { - } - print "<para>\n"; - output_highlight($args{'sections'}{$section}); - $output_preformatted = 0; - print "</para>\n"; - if ($section =~ m/EXAMPLE/i) { - print "</programlisting></example>\n"; - } else { - } - print " </simplesect>\n"; - } - - print "</sect2>\n\n"; -} - ## # output function in man sub output_function_man(%) {
@@ -1692,161 +738,6 @@ sub output_blockhead_man(%) { } ## -# output in text -sub output_function_text(%) { - my %args = %{$_[0]}; - my ($parameter, $section); - my $start; - - print "Name:\n\n"; - print $args{'function'} . " - " . $args{'purpose'} . "\n"; - - print "\nSynopsis:\n\n"; - if ($args{'functiontype'} ne "") { - $start = $args{'functiontype'} . " " . $args{'function'} . " ("; - } else { - $start = $args{'function'} . " ("; - } - print $start; - - my $count = 0; - foreach my $parameter (@{$args{'parameterlist'}}) { - $type = $args{'parametertypes'}{$parameter}; - if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { - # pointer-to-function - print $1 . $parameter . ") (" . $2; - } else { - print $type . " " . $parameter; - } - if ($count != $#{$args{'parameterlist'}}) { - $count++; - print ",\n"; - print " " x length($start); - } else { - print ");\n\n"; - } - } - - print "Arguments:\n\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - my $parameter_name = $parameter; - $parameter_name =~ s/\[.*//; - - print $parameter . "\n\t" . $args{'parameterdescs'}{$parameter_name} . "\n"; - } - output_section_text(@_); -} - -#output sections in text -sub output_section_text(%) { - my %args = %{$_[0]}; - my $section; - - print "\n"; - foreach $section (@{$args{'sectionlist'}}) { - print "$section:\n\n"; - output_highlight($args{'sections'}{$section}); - } - print "\n\n"; -} - -# output enum in text -sub output_enum_text(%) { - my %args = %{$_[0]}; - my ($parameter); - my $count; - print "Enum:\n\n"; - - print "enum " . $args{'enum'} . " - " . $args{'purpose'} . "\n\n"; - print "enum " . $args{'enum'} . " {\n"; - $count = 0; - foreach $parameter (@{$args{'parameterlist'}}) { - print "\t$parameter"; - if ($count != $#{$args{'parameterlist'}}) { - $count++; - print ","; - } - print "\n"; - } - print "};\n\n"; - - print "Constants:\n\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - print "$parameter\n\t"; - print $args{'parameterdescs'}{$parameter} . "\n"; - } - - output_section_text(@_); -} - -# output typedef in text -sub output_typedef_text(%) { - my %args = %{$_[0]}; - my ($parameter); - my $count; - print "Typedef:\n\n"; - - print "typedef " . $args{'typedef'} . " - " . $args{'purpose'} . "\n"; - output_section_text(@_); -} - -# output struct as text -sub output_struct_text(%) { - my %args = %{$_[0]}; - my ($parameter); - - print $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "\n\n"; - print $args{'type'} . " " . $args{'struct'} . " {\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - if ($parameter =~ /^#/) { - print "$parameter\n"; - next; - } - - my $parameter_name = $parameter; - $parameter_name =~ s/\[.*//; - - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; - $type = $args{'parametertypes'}{$parameter}; - if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { - # pointer-to-function - print "\t$1 $parameter) ($2);\n"; - } elsif ($type =~ m/^(.*?)\s*(:.*)/) { - # bitfield - print "\t$1 $parameter$2;\n"; - } else { - print "\t" . $type . " " . $parameter . ";\n"; - } - } - print "};\n\n"; - - print "Members:\n\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - ($parameter =~ /^#/) && next; - - my $parameter_name = $parameter; - $parameter_name =~ s/\[.*//; - - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; - print "$parameter\n\t"; - print $args{'parameterdescs'}{$parameter_name} . "\n"; - } - print "\n"; - output_section_text(@_); -} - -sub output_blockhead_text(%) { - my %args = %{$_[0]}; - my ($parameter, $section); - - foreach $section (@{$args{'sectionlist'}}) { - print " $section:\n"; - print " -> "; - output_highlight($args{'sections'}{$section}); - } -} - -## # output in restructured text #
@@ -2080,43 +971,6 @@ sub output_struct_rst(%) { output_section_rst(@_); } - -## list mode output functions - -sub output_function_list(%) { - my %args = %{$_[0]}; - - print $args{'function'} . "\n"; -} - -# output enum in list -sub output_enum_list(%) { - my %args = %{$_[0]}; - print $args{'enum'} . "\n"; -} - -# output typedef in list -sub output_typedef_list(%) { - my %args = %{$_[0]}; - print $args{'typedef'} . "\n"; -} - -# output struct as list -sub output_struct_list(%) { - my %args = %{$_[0]}; - - print $args{'struct'} . "\n"; -} - -sub output_blockhead_list(%) { - my %args = %{$_[0]}; - my ($parameter, $section); - - foreach $section (@{$args{'sectionlist'}}) { - print "DOC: $section\n"; - } -} - ## # generic output function for all types (function, struct/union, typedef, enum); # calls the generated, variable output_ function name based on
@@ -2804,7 +1658,7 @@ sub process_proto_type($$) { # just before actual output; (this is done by local_unescape()) sub xml_escape($) { my $text = shift; - if (($output_mode eq "text") || ($output_mode eq "man")) { + if ($output_mode eq "man") { return $text; } $text =~ s/\&/\\\\\\amp;/g;
@@ -2816,7 +1670,7 @@ sub xml_escape($) { # xml_unescape: reverse the effects of xml_escape sub xml_unescape($) { my $text = shift; - if (($output_mode eq "text") || ($output_mode eq "man")) { + if ($output_mode eq "man") { return $text; } $text =~ s/\\\\\\amp;/\&/g;
@@ -2829,7 +1683,7 @@ sub xml_unescape($) { # local escape strings look like: '\\\\menmonic:' (that's 4 backslashes) sub local_unescape($) { my $text = shift; - if (($output_mode eq "text") || ($output_mode eq "man")) { + if ($output_mode eq "man") { return $text; } $text =~ s/\\\\\\\\lt:/</g;
@@ -3149,34 +2003,6 @@ sub process_file($) { if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) { print STDERR " Was looking for '$_'.\n" for keys %function_table; } - if ($output_mode eq "xml") { - # The template wants at least one RefEntry here; make one. - print "<refentry>\n"; - print " <refnamediv>\n"; - print " <refname>\n"; - print " ${orig_file}\n"; - print " </refname>\n"; - print " <refpurpose>\n"; - print " Document generation inconsistency\n"; - print " </refpurpose>\n"; - print " </refnamediv>\n"; - print " <refsect1>\n"; - print " <title>\n"; - print " Oops\n"; - print " </title>\n"; - print " <warning>\n"; - print " <para>\n"; - print " The template for this document tried to insert\n"; - print " the structured comment from the file\n"; - print " <filename>${orig_file}</filename> at this point,\n"; - print " but none was found.\n"; - print " This dummy section is inserted to allow\n"; - print " generation to continue.\n"; - print " </para>\n"; - print " </warning>\n"; - print " </refsect1>\n"; - print "</refentry>\n"; - } } }
Signature · 1 line
2.13.6
PATCH v3 9/17 scripts: kernel-doc: improve argument handling
In reply to Mauro Carvalho ChehabRight now, if one uses "--rst" instead of "-rst", it just ignore the argument and produces a man page. Change the logic to accept both "-cmd" and "--cmd". Also, if "cmd" doesn't exist, print the usage information and exit.
--- scripts/kernel-doc | 34 +++++++++++++++++++--------------- 1 file changed, 19 insertions(+), 15 deletions(-)
scripts/kernel-doc +19 -15
@@ -390,45 +390,49 @@ my $undescribed = "-- undescribed --"; reset_state(); -while ($ARGV[0] =~ m/^-(.*)/) { - my $cmd = shift @ARGV; - if ($cmd eq "-man") { +while ($ARGV[0] =~ m/^--?(.*)/) { + my $cmd = $1; + shift @ARGV; + if ($cmd eq "man") { $output_mode = "man"; @highlights = @highlights_man; $blankline = $blankline_man; - } elsif ($cmd eq "-rst") { + } elsif ($cmd eq "rst") { $output_mode = "rst"; @highlights = @highlights_rst; $blankline = $blankline_rst; - } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document + } elsif ($cmd eq "module") { # not needed for XML, inherits from calling document $modulename = shift @ARGV; - } elsif ($cmd eq "-function") { # to only output specific functions + } elsif ($cmd eq "function") { # to only output specific functions $output_selection = OUTPUT_INCLUDE; $function = shift @ARGV; $function_table{$function} = 1; - } elsif ($cmd eq "-nofunction") { # output all except specific functions + } elsif ($cmd eq "nofunction") { # output all except specific functions $output_selection = OUTPUT_EXCLUDE; $function = shift @ARGV; $function_table{$function} = 1; - } elsif ($cmd eq "-export") { # only exported symbols + } elsif ($cmd eq "export") { # only exported symbols $output_selection = OUTPUT_EXPORTED; %function_table = (); - } elsif ($cmd eq "-internal") { # only non-exported symbols + } elsif ($cmd eq "internal") { # only non-exported symbols $output_selection = OUTPUT_INTERNAL; %function_table = (); - } elsif ($cmd eq "-export-file") { + } elsif ($cmd eq "export-file") { my $file = shift @ARGV; push(@export_file_list, $file); - } elsif ($cmd eq "-v") { + } elsif ($cmd eq "v") { $verbose = 1; - } elsif (($cmd eq "-h") || ($cmd eq "--help")) { + } elsif (($cmd eq "h") || ($cmd eq "help")) { usage(); - } elsif ($cmd eq '-no-doc-sections') { + } elsif ($cmd eq 'no-doc-sections') { $no_doc_sections = 1; - } elsif ($cmd eq '-enable-lineno') { + } elsif ($cmd eq 'enable-lineno') { $enable_lineno = 1; - } elsif ($cmd eq '-show-not-found') { + } elsif ($cmd eq 'show-not-found') { $show_not_found = 1; + } else { + # Unknown argument + usage(); } }
Signature · 1 line
2.13.6
PATCH v3 10/17 scripts: kernel-doc: change default to ReST format
In reply to Mauro Carvalho ChehabRight now, if kernel-doc is called without arguments, it defaults to man pages. IMO, it makes more sense to default to ReST, as this is the output that it is most used nowadays, and it easier to check if everything got parsed fine on an enriched text mode format.
--- scripts/kernel-doc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
scripts/kernel-doc +3 -3
@@ -267,12 +267,12 @@ my $kernelversion; my $dohighlight = ""; my $verbose = 0; -my $output_mode = "man"; +my $output_mode = "rst"; my $output_preformatted = 0; my $no_doc_sections = 0; my $enable_lineno = 0; -my @highlights = @highlights_man; -my $blankline = $blankline_man; +my @highlights = @highlights_rst; +my $blankline = $blankline_rst; my $modulename = "Kernel API"; use constant {
Signature · 1 line
2.13.6
PATCH v3 11/17 scripts: kernel-doc: replace tabs by spaces
In reply to Mauro Carvalho ChehabSphinx has a hard time dealing with tabs, causing it to misinterpret paragraph continuation.
As we're now mainly focused on supporting ReST output, replace tabs by spaces, in order to avoid troubles when the output is parsed by Sphinx.
--- scripts/kernel-doc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-)
scripts/kernel-doc +5 -5
@@ -1557,7 +1557,7 @@ sub tracepoint_munge($) { sub syscall_munge() { my $void = 0; - $prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs + $prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's ## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) { if ($prototype =~ m/SYSCALL_DEFINE0/) { $void = 1;
@@ -1756,6 +1756,8 @@ sub process_file($) { while (s/\\\s*$//) { $_ .= <IN>; } + # Replace tabs by spaces + while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}; if ($state == STATE_NORMAL) { if (/$doc_start/o) { $state = STATE_NAME; # next line is always the function name
@@ -1855,8 +1857,7 @@ sub process_file($) { $in_purpose = 0; $contents = $newcontents; $new_start_line = $.; - while ((substr($contents, 0, 1) eq " ") || - substr($contents, 0, 1) eq "\t") { + while (substr($contents, 0, 1) eq " ") { $contents = substr($contents, 1); } if ($contents ne "") {
@@ -1925,8 +1926,7 @@ sub process_file($) { $contents = $2; $new_start_line = $.; if ($contents ne "") { - while ((substr($contents, 0, 1) eq " ") || - substr($contents, 0, 1) eq "\t") { + while (substr($contents, 0, 1) eq " ") { $contents = substr($contents, 1); } $contents .= "\n";
Signature · 1 line
2.13.6
PATCH v3 12/17 scripts: kernel-doc: parse next structs/unions
In reply to Mauro Carvalho ChehabThere 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 clockWith 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.
--- Documentation/doc-guide/kernel-doc.rst | 46 +++++++++++++ scripts/kernel-doc | 121 ++++++++++++++++++--------------- 2 files changed, 114 insertions(+), 53 deletions(-)
Documentation/doc-guide/kernel-doc.rst +46 -0
@@ -281,6 +281,52 @@ comment block. The kernel-doc data structure comments describe each member of the structure, in order, with the member descriptions. +Nested structs/unions +~~~~~~~~~~~~~~~~~~~~~ + +It is possible to document nested structs unions, like:: + + /** + * struct nested_foobar - a struct with nested unions and structs + * @arg1: - first argument of anonymous union/anonymous struct + * @arg2: - 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.st2.arg1 - first argument of struct st2 on union bar + * @bar.st2.arg2 - second argument of struct st2 on union bar + struct nested_foobar { + /* Anonymous union/struct*/ + union { + struct { + int arg1; + int arg2; + } + struct { + void *arg3; + int arg4; + } + } + union { + struct { + int arg1; + int arg2; + } st1; + struct { + void *arg1; + int arg2; + } st2; + } bar; + }; + +.. note:: + + #) When documenting nested structs or unions, if the struct/union ``foo`` + is named, the argument ``bar`` inside it should be documented as + ``@foo.bar:`` + #) When the nested struct/union is anonymous, the argument ``bar`` on it + should be documented as ``@bar:`` Typedef documentation ---------------------
scripts/kernel-doc +68 -53
165 lines not on this page · raw message
Signature · 1 line
2.13.6
PATCH v3 13/17 scripts: kernel-doc: get rid of $nested parameter
In reply to Mauro Carvalho ChehabThe check_sections() function has a $nested parameter, meant to identify when a nested struct is present. As we now have a logic that handles it, get rid of such parameter.
--- scripts/kernel-doc | 19 ++++--------------- 1 file changed, 4 insertions(+), 15 deletions(-)
scripts/kernel-doc +4 -15
@@ -983,7 +983,6 @@ sub dump_union($$) { sub dump_struct($$) { my $x = shift; my $file = shift; - my $nested; if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) { my $decl_type = $1;
@@ -1041,11 +1040,9 @@ sub dump_struct($$) { # Ignore other nested elements, like enums $members =~ s/({[^\{\}]*})//g; - $nested = $decl_type; - $nested =~ s/\/\*.*?\*\///gos; create_parameterlist($members, ';', $file); - check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual, $nested); + check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual); # Adjust declaration for better display $declaration =~ s/([{;])/$1\n/g;
@@ -1350,8 +1347,8 @@ sub push_parameter($$$) { $parametertypes{$param} = $type; } -sub check_sections($$$$$$) { - my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_; +sub check_sections($$$$$) { + my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) = @_; my @sects = split ' ', $sectcheck; my @prms = split ' ', $prmscheck; my $err;
@@ -1385,14 +1382,6 @@ sub check_sections($$$$$$) { "'$sects[$sx]' " . "description in '$decl_name'\n"; ++$warnings; - } else { - if ($nested !~ m/\Q$sects[$sx]\E/) { - print STDERR "${file}:$.: warning: " . - "Excess $decl_type member " . - "'$sects[$sx]' " . - "description in '$decl_name'\n"; - ++$warnings; - } } } }
@@ -1503,7 +1492,7 @@ sub dump_function($$) { } my $prms = join " ", @parameterlist; - check_sections($file, $declaration_name, "function", $sectcheck, $prms, ""); + check_sections($file, $declaration_name, "function", $sectcheck, $prms); # This check emits a lot of warnings at the moment, because many # functions don't have a 'Return' doc section. So until the number
Signature · 1 line
2.13.6
PATCH v3 14/17 scripts: kernel-doc: print the declaration name on warnings
In reply to Mauro Carvalho ChehabThe 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.
--- scripts/kernel-doc | 38 ++++++++++++++++---------------------- 1 file changed, 16 insertions(+), 22 deletions(-)
scripts/kernel-doc +16 -22
@@ -1041,7 +1041,7 @@ sub dump_struct($$) { # Ignore other nested elements, like enums $members =~ s/({[^\{\}]*})//g; - create_parameterlist($members, ';', $file); + create_parameterlist($members, ';', $file, $declaration_name); check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual); # Adjust declaration for better display
@@ -1150,7 +1150,7 @@ sub dump_typedef($$) { $declaration_name = $2; my $args = $3; - create_parameterlist($args, ',', $file); + create_parameterlist($args, ',', $file, $declaration_name); output_declaration($declaration_name, 'function',
@@ -1199,10 +1199,11 @@ sub save_struct_actual($) { $struct_actual = $struct_actual . $actual . " "; } -sub create_parameterlist($$$) { +sub create_parameterlist($$$$) { my $args = shift; my $splitter = shift; my $file = shift; + my $declaration_name = shift; my $type; my $param;
@@ -1232,7 +1233,7 @@ sub create_parameterlist($$$) { $type = $arg; $type =~ s/([^\(]+\(\*?)\s*$param/$1/; save_struct_actual($param); - push_parameter($param, $type, $file); + push_parameter($param, $type, $file, $declaration_name); } elsif ($arg) { $arg =~ s/\s*:\s*/:/g; $arg =~ s/\s*\[/\[/g;
@@ -1257,27 +1258,28 @@ sub create_parameterlist($$$) { foreach $param (@args) { if ($param =~ m/^(\*+)\s*(.*)/) { save_struct_actual($2); - push_parameter($2, "$type $1", $file); + push_parameter($2, "$type $1", $file, $declaration_name); } elsif ($param =~ m/(.*?):(\d+)/) { if ($type ne "") { # skip unnamed bit-fields save_struct_actual($1); - push_parameter($1, "$type:$2", $file) + push_parameter($1, "$type:$2", $file, $declaration_name) } } else { save_struct_actual($param); - push_parameter($param, $type, $file); + push_parameter($param, $type, $file, $declaration_name); } } } } } -sub push_parameter($$$) { +sub push_parameter($$$$) { my $param = shift; my $type = shift; my $file = shift; + my $declaration_name = shift; if (($anon_struct_union == 1) && ($type eq "") && ($param eq "}")) {
@@ -1314,21 +1316,13 @@ sub push_parameter($$$) { # warn if parameter has no description # (but ignore ones starting with # as these are not parameters # but inline preprocessor statements); - # also ignore unnamed structs/unions; - if (!$anon_struct_union) { + # Note: It will also ignore void params and unnamed structs/unions if (!defined $parameterdescs{$param} && $param !~ /^#/) { + $parameterdescs{$param} = $undescribed; - $parameterdescs{$param} = $undescribed; - - if (($type eq 'function') || ($type eq 'enum')) { - print STDERR "${file}:$.: warning: Function parameter ". - "or member '$param' not " . - "described in '$declaration_name'\n"; - } - print STDERR "${file}:$.: warning:" . - " No description found for parameter '$param'\n"; - ++$warnings; - } + print STDERR + "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n"; + ++$warnings; } $param = xml_escape($param);
@@ -1485,7 +1479,7 @@ sub dump_function($$) { $declaration_name = $2; my $args = $3; - create_parameterlist($args, ',', $file); + create_parameterlist($args, ',', $file, $declaration_name); } else { print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n"; return;
Signature · 1 line
2.13.6
PATCH v3 15/17 scripts: kernel-doc: handle nested struct function arguments
In reply to Mauro Carvalho ChehabFunction arguments are different than usual ones. So, an special logic is needed in order to handle such arguments on nested structs.
--- scripts/kernel-doc | 38 ++++++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 12 deletions(-)
scripts/kernel-doc +26 -12
@@ -1019,18 +1019,32 @@ sub dump_struct($$) { $id =~ s/^\*+//; foreach my $arg (split /;/, $content) { next if ($arg =~ m/^\s*$/); - my $type = $arg; - my $name = $arg; - $type =~ s/\s\S+$//; - $name =~ s/.*\s//; - $name =~ s/[:\[].*//; - $name =~ s/^\*+//; - next if (($name =~ m/^\s*$/)); - if ($id =~ m/^\s*$/) { - # anonymous struct/union - $newmember .= "$type $name;"; + 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 + $newmember .= "$type$name$extra;"; + } else { + $newmember .= "$type$id.$name$extra;"; + } } else { - $newmember .= "$type $id.$name;"; + my $type = $arg; + my $name = $arg; + $type =~ s/\s\S+$//; + $name =~ s/.*\s+//; + $name =~ s/[:\[].*//; + $name =~ s/^\*+//; + next if (($name =~ m/^\s*$/)); + if ($id =~ m/^\s*$/) { + # anonymous struct/union + $newmember .= "$type $name;"; + } else { + $newmember .= "$type $id.$name;"; + } } } $members =~ s/(struct|union)([^{};]+){([^{}]*)}([^{}\;]*)\;/$newmember/;
@@ -1228,7 +1242,7 @@ sub create_parameterlist($$$$) { } elsif ($arg =~ m/\(.+\)\s*\(/) { # pointer-to-function $arg =~ tr/#/,/; - $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/; + $arg =~ m/[^\(]+\(\*?\s*([\w\.]*)\s*\)/; $param = $1; $type = $arg; $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
Signature · 1 line
2.13.6
PATCH v3 16/17 scripts: kernel-doc: improve nested logic to handle multiple identifiers
In reply to Mauro Carvalho ChehabIt 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'
--- scripts/kernel-doc | 69 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 44 insertions(+), 25 deletions(-)
scripts/kernel-doc +44 -25
@@ -1008,15 +1008,16 @@ sub dump_struct($$) { my $declaration = $members; # Split nested struct/union elements as newer ones - my $cont = 1; - while ($cont) { - $cont = 0; - while ($members =~ m/(struct|union)([^{};]+){([^{}]*)}([^{}\;]*)\;/) { - my $newmember = "$1 $4;"; - my $id = $4; - my $content = $3; + while ($members =~ m/(struct|union)([^{};]+){([^{}]*)}([^{}\;]*)\;/) { + my $newmember; + my $maintype = $1; + my $ids = $4; + my $content = $3; + foreach my $id(split /,/, $ids) { + $newmember .= "$maintype $id; "; + $id =~ s/[:\[].*//; - $id =~ s/^\*+//; + $id =~ s/^\s*\**(\S+)\s*/$1/; foreach my $arg (split /;/, $content) { next if ($arg =~ m/^\s*$/); if ($arg =~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) {
@@ -1027,30 +1028,48 @@ sub dump_struct($$) { next if (!$name); if ($id =~ m/^\s*$/) { # anonymous struct/union - $newmember .= "$type$name$extra;"; + $newmember .= "$type$name$extra; "; } else { - $newmember .= "$type$id.$name$extra;"; + $newmember .= "$type$id.$name$extra; "; } } else { - my $type = $arg; - my $name = $arg; - $type =~ s/\s\S+$//; - $name =~ s/.*\s+//; - $name =~ s/[:\[].*//; - $name =~ s/^\*+//; - next if (($name =~ m/^\s*$/)); - if ($id =~ m/^\s*$/) { - # anonymous struct/union - $newmember .= "$type $name;"; + 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; } else { - $newmember .= "$type $id.$name;"; + $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; "; + } } } } - $members =~ s/(struct|union)([^{};]+){([^{}]*)}([^{}\;]*)\;/$newmember/; - $cont = 1; - }; - }; + } + $members =~ s/(struct|union)([^{};]+){([^{}]*)}([^{}\;]*)\;/$newmember/; + } # Ignore other nested elements, like enums $members =~ s/({[^\{\}]*})//g;
Signature · 1 line
2.13.6
PATCH v3 17/17 w1_netlink.h: add support for nested structs
In reply to Mauro Carvalho ChehabNow that kernel-doc can hanle nested structs/unions, describe such fields at w1_netlink_message_types.
--- drivers/w1/w1_netlink.h | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-)
drivers/w1/w1_netlink.h +5 -1
@@ -59,7 +59,11 @@ enum w1_netlink_message_types {* @type: one of enum w1_netlink_message_types * @status: kernel feedback for success 0 or errno failure value * @len: length of data following w1_netlink_msg -* @id: union holding master bus id (msg.id) and slave device id (id[8]). +* @id: union holding bus master id (msg.id) and slave device id (id[8]). +* @id.id: Slave ID (8 bytes) +* @id.mst: bus master identification +* @id.mst.id: bus master ID +* @id.mst.res: bus master reserved * @data: start address of any following data * * The base message structure for w1 messages over netlink.
Signature · 1 line
2.13.6
Jonathan Corbet
maintainerQuoted 4 lines · On Wed, 4 Oct 2017 08:48:38 -0300 Mauro Carvalho Chehab…
Right now, it is not possible to document nested struct and nested unions. kernel-doc simply ignore them.
Add support to document them.
So I've finally found some time to actually look at these; sorry for being so absent from the discussion. I plead $EXCUSES...
Some overall impressions:
- Seems like something we want.
- I love hacking all the cruft out of kernel-doc; I've been meaning to do that for a bit.
- It would sure be nice to restore proper man-page generation rather than documenting a hack with a perl script. Someday.
I have one real complaint, though: with these patches applied, a "make htmldocs" generates about 5500 (!) more warnings than it did before. Over the last couple of months, I put a bit of focused time into reducing warnings, and managed to get rid of 20-30 of them. Now I feel despondent.
I really don't want to add that much noise to the docs build; I think it will defeat any hope of cleaning up the warnings we already have. I wonder if we could suppress warnings about nested structs by default, and add a flag or envar to turn them back on for those who want them?
In truth, now that I look, the real problem is that the warnings are repeated many times - as in, like 100 times:
Quoted 2 lines
./include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'./include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'
<107 instances deleted...>
Quoted 1 line
./include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'
That's not something that used to happen, and is certainly not helpful. Figuring that out would help a lot. Can I get you to take a look at what's going on here?
Thanks,
jon
Quoted 27 lines
Am 07.10.2017 um 18:34 schrieb Jonathan Corbet <[email protected]>:
Quoted 4 lines · On Wed, 4 Oct 2017 08:48:38 -0300 Mauro Carvalho Chehab…
Right now, it is not possible to document nested struct and nested unions. kernel-doc simply ignore them.
Add support to document them.
So I've finally found some time to actually look at these; sorry for being so absent from the discussion. I plead $EXCUSES...
Some overall impressions:
- Seems like something we want.
- I love hacking all the cruft out of kernel-doc; I've been meaning to do that for a bit.
- It would sure be nice to restore proper man-page generation rather than documenting a hack with a perl script. Someday.I have one real complaint, though: with these patches applied, a "make htmldocs" generates about 5500 (!) more warnings than it did before. Over the last couple of months, I put a bit of focused time into reducing warnings, and managed to get rid of 20-30 of them. Now I feel despondent.
Quoted 4 lines
I really don't want to add that much noise to the docs build; I think it will defeat any hope of cleaning up the warnings we already have. I wonder if we could suppress warnings about nested structs by default, and add a flag or envar to turn them back on for those who want them?
This is what I vote for: +1
Quoted 11 lines
In truth, now that I look, the real problem is that the warnings are repeated many times - as in, like 100 times:
Quoted 2 lines
./include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'./include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'<107 instances deleted...>
Quoted 1 line
./include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'That's not something that used to happen, and is certainly not helpful. Figuring that out would help a lot. Can I get you to take a look at what's going on here?
Hi Jon, if you grep for
.. kernel-doc:: include/net/cfg80211.h
e.g. by: grep cfg80211.h Documentation/driver-api/80211/cfg80211.rst | wc -l you will see, that this directive is used 110 times in one reST file. If you have 5 warnings about the kernel-doc markup in include/net/cfg80211.h you will get 550 warnings about kernel-doc markup just for just one source code file.
This is because the kernel-doc parser is an external process which is called (in this example) 110 times for one reST file and one source code file. If include/net/cfg80211.h is referred in other reST files, we got accordingly more and more warnings .. thats really noise.
So what I see is, that a major part of such noise is self made, it was one major goal when I started with the python implementation: run kernel-doc parser in the Sphinx process, cache the results and use it in all reST files where it is required from a kernel-doc directive.
Since there is also a man page solution in the py- version I vote to merge the py-version into the kernel (ATM man is similar to what we had in DocBook and it is expandable). If you want to have a preview of the result, try this patch:
https://return42.github.io/linuxdoc/linux.html
The only drawback of the py version I see is, that Mauro prefers perl and I do not want to lose him as an contributer to the kernel-doc parser. IMO he is an experienced C programmer with an excellent regexpr knowledge. This is, what is needed for this job. May be we can motivate him to give python one more try, this is what I hope.
The py version includes all patches we had to the perl version, but I also know, that you are not 100% compliant with the coding style, this could all be fixed in a RFC round. Excuse me if I annoying with this solution; IMO it contains what we need, if we really want to make a step forward.
Thanks,
-- Markus --
Quoted 9 lines
Thanks,
jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Em Sun, 8 Oct 2017 12:07:29 +0200
Markus Heiser <[email protected]> escreveu:
Quoted 5 lines
Quoted 5 lines
Am 07.10.2017 um 18:34 schrieb Jonathan Corbet <[email protected]>:
On Wed, 4 Oct 2017 08:48:38 -0300
Mauro Carvalho Chehab <[email protected]> wrote:
Quoted 7 lines
Quoted 7 lines
Quoted 4 lines
Right now, it is not possible to document nested struct and nested unions. kernel-doc simply ignore them.
Add support to document them.
So I've finally found some time to actually look at these; sorry for being so absent from the discussion. I plead $EXCUSES...
Thanks for looking into it!
Quoted 9 lines
Quoted 9 lines
Some overall impressions:
- Seems like something we want.
- I love hacking all the cruft out of kernel-doc; I've been meaning to do that for a bit.
- It would sure be nice to restore proper man-page generation rather than documenting a hack with a perl script. Someday.
Quoted 4 lines
Quoted 4 lines
I have one real complaint, though: with these patches applied, a "make htmldocs" generates about 5500 (!) more warnings than it did before. Over the last couple of months, I put a bit of focused time into reducing warnings, and managed to get rid of 20-30 of them. Now I feel despondent.
Yeah, I know the feeling...
Quoted 29 lines
Quoted 5 lines
I really don't want to add that much noise to the docs build; I think it will defeat any hope of cleaning up the warnings we already have. I wonder if we could suppress warnings about nested structs by default, and add a flag or envar to turn them back on for those who want them?
This is what I vote for: +1
Quoted 11 lines
In truth, now that I look, the real problem is that the warnings are repeated many times - as in, like 100 times:
Quoted 2 lines
./include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'./include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'<107 instances deleted...>
Quoted 1 line
./include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'That's not something that used to happen, and is certainly not helpful. Figuring that out would help a lot. Can I get you to take a look at what's going on here?
Hi Jon, if you grep for
.. kernel-doc::
include/net/cfg80211.he.g. by: grep
cfg80211.hDocumentation/driver-api/80211/cfg80211.rst| wc -l you will see, that this directive is used 110 times in one reST file. If you have 5 warnings about the kernel-doc markup ininclude/net/cfg80211.hyou will get 550 warnings about kernel-doc markup just for just one source code file.
Quoted 4 lines
This is because the kernel-doc parser is an external process which is called (in this example) 110 times for one reST file and one source code file. If
include/net/cfg80211.his referred in other reST files, we got accordingly more and more warnings .. thats really noise.
I guess the solution here is simple: if any output selection argument is passed (-export, -internal, -function, -nofunction), only report warnings for things that match the output criteria.
Not sure how easy is to implement that. I'll take a look.
Quoted 17 lines
So what I see is, that a major part of such noise is self made, it was one major goal when I started with the python implementation: run kernel-doc parser in the Sphinx process, cache the results and use it in all reST files where it is required from a kernel-doc directive.
Since there is also a man page solution in the py- version I vote to merge the py-version into the kernel (ATM man is similar to what we had in DocBook and it is expandable). If you want to have a preview of the result, try this patch:
https://return42.github.io/linuxdoc/linux.html
The only drawback of the py version I see is, that Mauro prefers perl and I do not want to lose him as an contributer to the kernel-doc parser. IMO he is an experienced C programmer with an excellent regexpr knowledge. This is, what is needed for this job. May be we can motivate him to give python one more try, this is what I hope.
Quoted 4 lines
The py version includes all patches we had to the perl version, but I also know, that you are not 100% compliant with the coding style, this could all be fixed in a RFC round. Excuse me if I annoying with this solution; IMO it contains what we need, if we really want to make a step forward.
I can probably submit regex patches, no matter if it is perl or python.
I actually submitted several patches patchwork, in the past, and I'm doing lately some contributions to Solaar, with is written in python, in order to fix support for my mice.
The thing is that it takes me more time to write code in Python, as I never had the time to study the language. So, I learned what I needed there by coding.
Thanks,
Mauro
Em Mon, 9 Oct 2017 10:19:55 -0300
Mauro Carvalho Chehab <[email protected]> escreveu:
Quoted 33 lines
Quoted 28 lines
Quoted 4 lines
I really don't want to add that much noise to the docs build; I think it will defeat any hope of cleaning up the warnings we already have. I wonder if we could suppress warnings about nested structs by default, and add a flag or envar to turn them back on for those who want them?
This is what I vote for: +1
Quoted 11 lines
In truth, now that I look, the real problem is that the warnings are repeated many times - as in, like 100 times:
Quoted 2 lines
./include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'./include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'<107 instances deleted...>
Quoted 1 line
./include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'That's not something that used to happen, and is certainly not helpful. Figuring that out would help a lot. Can I get you to take a look at what's going on here?
Hi Jon, if you grep for
.. kernel-doc::
include/net/cfg80211.he.g. by: grep
cfg80211.hDocumentation/driver-api/80211/cfg80211.rst| wc -l you will see, that this directive is used 110 times in one reST file. If you have 5 warnings about the kernel-doc markup ininclude/net/cfg80211.hyou will get 550 warnings about kernel-doc markup just for just one source code file.Quoted 4 lines
This is because the kernel-doc parser is an external process which is called (in this example) 110 times for one reST file and one source code file. If
include/net/cfg80211.his referred in other reST files, we got accordingly more and more warnings .. thats really noise.
Quoted 5 lines
I guess the solution here is simple: if any output selection argument is passed (-export, -internal, -function, -nofunction), only report warnings for things that match the output criteria.
Not sure how easy is to implement that. I'll take a look.
It is actually very easy to suppress those warnings. See the enclosed proof of concept patch.
Please notice that this patch is likely incomplete: all it does is that, if --function or --nofunction is used, it won't print any warnings for structs or enums.
I didn't check yet if this is not making it too silent.
If we're going to follow this way, IMHO, the best would be to define a warning function and move the needed checks for $output_selection and for $function for it to do the right thing, printing warnings only for the stuff that will be output.
Jon,
Please let me know if you prefer go though this way or if, instead, you opt to replace the kernel-doc perl script by a Sphinx module.
If you decide to keep with the perl script for now, I can work on an improved version of this PoC.
Regards,
Mauro
scripts: kernel-doc: shut up enum/struct warnings if parsing only functions
There are two command line parameters that restrict the kernel-doc output to output only functions. If this is used, it doesn't make any sense to produce warnings about enums and structs. So, shut up such warnings.
scripts/kernel-doc +14 -7
@@ -1138,16 +1138,20 @@ sub dump_enum($$) { push @parameterlist, $arg; if (!$parameterdescs{$arg}) { $parameterdescs{$arg} = $undescribed; - print STDERR "${file}:$.: warning: Enum value '$arg' ". - "not described in enum '$declaration_name'\n"; + if ($output_selection != OUTPUT_INCLUDE && + $output_selection != OUTPUT_EXCLUDE) { + print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum '$declaration_name'\n"; + } } $_members{$arg} = 1; } while (my ($k, $v) = each %parameterdescs) { if (!exists($_members{$k})) { - print STDERR "${file}:$.: warning: Excess enum value " . - "'$k' description in '$declaration_name'\n"; + if ($output_selection != OUTPUT_INCLUDE && + $output_selection != OUTPUT_EXCLUDE) { + print STDERR "${file}:$.: warning: Excess enum value '$k' description in '$declaration_name'\n"; + } } }
@@ -1353,9 +1357,12 @@ sub push_parameter($$$$) { if (!defined $parameterdescs{$param} && $param !~ /^#/) { $parameterdescs{$param} = $undescribed; - print STDERR - "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n"; - ++$warnings; + if ($output_selection != OUTPUT_INCLUDE && + $output_selection != OUTPUT_EXCLUDE) { + print STDERR + "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n"; + ++$warnings; + } } $param = xml_escape($param);
Em Wed, 4 Oct 2017 08:48:38 -0300
Mauro Carvalho Chehab <[email protected]> escreveu:
Quoted 41 lines
Right now, it is not possible to document nested struct and nested unions. kernel-doc simply ignore them.
Add support to document them.
Patches 1 to 6 improve kernel-doc documentation to reflect what kernel-doc currently supports and import some stuff from the old kernel-doc-nano-HOWTO.txt.
Patch 7 gets rid of the old documentation (kernel-doc-nano-HOWTO.txt).
Patch 8 gets rid of the now unused output formats for kernel-doc: since we got rid of all DocBook stuff, we should not need them anymore. The reason for dropping it (despite cleaning up), is that it doesn't make sense to invest time on adding new features for formats that aren't used anymore.
Patch 9 improves argument handling, printing script usage if an invalid argument is passed and accepting both -cmd and --cmd forms.
Patch 10 changes the default output format to ReST, as this is a way more used than man output nowadays.
Patch 11 solves an issue after ReST conversion, where tabs were not properly handled on kernel-doc tags.
Patch 12 adds support for parsing kernel-doc nested structures and unions.
Patch 13 does a cleanup, removing $nexted parameter at the routines that handle structs.
Patch 14 Improves warning output by printing the identifier where the warning occurred.
Patch 15 complements patch 12, by adding support for function definitions inside nested structures. It is needed by some media docs with use such kind of things.
Quoted 8 lines
Patch 16 improves nested struct handling even further, allowing it to handle cases where a nested named struct/enum with multiple identifiers added (e. g. struct { ... } foo, bar;).
Patch 17 adds documentation for nested union/struct inside
w1_netlink.The entire patch series are at my development tree, at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=nested-fix-v4b
I'm applying all patches from this series that either didn't have any comments of whose editorial comments I fully embraced.
The patches that weren't applied from this series are:
0008-media-v4l2-device.h-document-ancillary-macros.patch 0010-media-v4l2-ioctl.h-convert-debug-macros-into-enum-an.patch 0014-media-v4l2-async-simplify-v4l2_async_subdev-structur.patch 0015-media-v4l2-async-better-describe-match-union-at-asyn.patch
I'll send later a patch series with those - probably together with other documentation patches from the other two series I sent - that need further reviews.
Thanks,
Mauro