From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
To: Linux Doc Mailing List <linux-doc@vger.kernel.org>,
Linux Media Mailing List <linux-media@vger.kernel.org>
Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>,
Mauro Carvalho Chehab <mchehab@infradead.org>,
linux-kernel@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>
Subject: [PATCH v3 16/17] scripts: kernel-doc: improve nested logic to handle multiple identifiers
Date: Wed, 4 Oct 2017 08:48:54 -0300 [thread overview]
Message-ID: <03fbd714e9c2def6f6a081ca27ca99f794a5bd0c.1507116877.git.mchehab@s-opensource.com> (raw)
In-Reply-To: <cover.1507116877.git.mchehab@s-opensource.com>
In-Reply-To: <cover.1507116877.git.mchehab@s-opensource.com>
It is possible to use nested structs like:
struct {
struct {
void *arg1;
} st1, st2, *st3, st4;
};
Handling it requires to split each parameter. Change the logic
to allow such definitions.
In order to test the new nested logic, the following file
was used to test
<code>
struct foo { int a; }; /* Just to avoid errors if compiled */
/**
* struct my_struct - a struct with nested unions and structs
* @arg1: first argument of anonymous union/anonymous struct
* @arg2: second argument of anonymous union/anonymous struct
* @arg1b: first argument of anonymous union/anonymous struct
* @arg2b: second argument of anonymous union/anonymous struct
* @arg3: third argument of anonymous union/anonymous struct
* @arg4: fourth argument of anonymous union/anonymous struct
* @bar.st1.arg1: first argument of struct st1 on union bar
* @bar.st1.arg2: second argument of struct st1 on union bar
* @bar.st1.bar1: bar1 at st1
* @bar.st1.bar2: bar2 at st1
* @bar.st2.arg1: first argument of struct st2 on union bar
* @bar.st2.arg2: second argument of struct st2 on union bar
* @bar.st3.arg2: second argument of struct st3 on union bar
* @f1: nested function on anonimous union/struct
* @bar.st2.f2: nested function on named union/struct
*/
struct my_struct {
/* Anonymous union/struct*/
union {
struct {
char arg1 : 1;
char arg2 : 3;
};
struct {
int arg1b;
int arg2b;
};
struct {
void *arg3;
int arg4;
int (*f1)(char foo, int bar);
};
};
union {
struct {
int arg1;
int arg2;
struct foo bar1, *bar2;
} st1; /* bar.st1 is undocumented, cause a warning */
struct {
void *arg1; /* bar.st3.arg1 is undocumented, cause a warning */
int arg2;
int (*f2)(char foo, int bar); /* bar.st3.fn2 is undocumented, cause a warning */
} st2, st3, *st4;
int (*f3)(char foo, int bar); /* f3 is undocumented, cause a warning */
} bar; /* bar is undocumented, cause a warning */
/* private: */
int undoc_privat; /* is undocumented but private, no warning */
/* public: */
int undoc_public; /* is undocumented, cause a warning */
};
</code>
It produces the following warnings, as expected:
test2.h:57: warning: Function parameter or member 'bar' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.f3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'undoc_public' not described in 'my_struct'
Suggested-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
scripts/kernel-doc | 69 ++++++++++++++++++++++++++++++++++--------------------
1 file changed, 44 insertions(+), 25 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 67e8712aa324..049044d95c0e 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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;
--
2.13.6
next prev parent reply other threads:[~2017-10-04 11:58 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-10-04 11:48 [PATCH v3 00/17] kernel-doc: add supported to document nested structs/ Mauro Carvalho Chehab
2017-10-04 11:48 ` [PATCH v3 01/17] docs: kernel-doc.rst: better describe kernel-doc arguments Mauro Carvalho Chehab
2017-10-04 11:48 ` [PATCH v3 02/17] docs: kernel-doc.rst: improve private members description Mauro Carvalho Chehab
2017-10-04 11:48 ` [PATCH v3 03/17] docs: kernel-doc.rst: improve function documentation section Mauro Carvalho Chehab
2017-10-04 11:48 ` [PATCH v3 04/17] docs: kernel-doc.rst: improve structs chapter Mauro Carvalho Chehab
2017-10-04 11:48 ` [PATCH v3 05/17] docs: kernel-doc.rst: improve typedef documentation Mauro Carvalho Chehab
2017-10-04 11:48 ` [PATCH v3 06/17] docs: kernel-doc.rst: add documentation about man pages Mauro Carvalho Chehab
2017-10-04 11:48 ` [PATCH v3 07/17] docs: get rid of kernel-doc-nano-HOWTO.txt Mauro Carvalho Chehab
2017-10-04 11:48 ` [PATCH v3 08/17] scripts: kernel-doc: get rid of unused output formats Mauro Carvalho Chehab
2017-10-04 11:48 ` [PATCH v3 09/17] scripts: kernel-doc: improve argument handling Mauro Carvalho Chehab
2017-10-04 11:48 ` [PATCH v3 10/17] scripts: kernel-doc: change default to ReST format Mauro Carvalho Chehab
2017-10-04 11:48 ` [PATCH v3 11/17] scripts: kernel-doc: replace tabs by spaces Mauro Carvalho Chehab
2017-10-04 11:48 ` [PATCH v3 12/17] scripts: kernel-doc: parse next structs/unions Mauro Carvalho Chehab
2017-10-04 11:48 ` [PATCH v3 13/17] scripts: kernel-doc: get rid of $nested parameter Mauro Carvalho Chehab
2017-10-04 11:48 ` [PATCH v3 14/17] scripts: kernel-doc: print the declaration name on warnings Mauro Carvalho Chehab
2017-10-04 11:48 ` [PATCH v3 15/17] scripts: kernel-doc: handle nested struct function arguments Mauro Carvalho Chehab
2017-10-04 11:48 ` Mauro Carvalho Chehab [this message]
2017-10-04 11:48 ` [PATCH v3 17/17] w1_netlink.h: add support for nested structs Mauro Carvalho Chehab
2017-10-07 16:34 ` [PATCH v3 00/17] kernel-doc: add supported to document nested structs/ Jonathan Corbet
2017-10-08 10:07 ` Markus Heiser
2017-10-09 13:19 ` Mauro Carvalho Chehab
2017-10-11 19:17 ` Mauro Carvalho Chehab
2017-12-18 15:26 ` Mauro Carvalho Chehab
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=03fbd714e9c2def6f6a081ca27ca99f794a5bd0c.1507116877.git.mchehab@s-opensource.com \
--to=mchehab@s-opensource.com \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-media@vger.kernel.org \
--cc=mchehab@infradead.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®