Em Tue, 06 Jun 2017 15:28:34 +0200
Johannes Berg <johannes@xxxxxxxxxxxxxxxx> escreveu:
> Hi,
>
> Apologies for the long CC list, wasn't sure who really feels like they
> understand this script anymore ... Markus, I think you had a rewrite of
> the script in python?
>
> If you have something like this:
>
> /**
> * struct something
> * @very_long_member_name: abcde
> */
> struct something {
> struct this_is_a_very_long_struct_name_so_need_to_break_for_the
> very_long_member_name;
> };
>
> then kernel-doc will mishandle it:
>
> $ ./scripts/kernel-doc -rst -internal /tmp/test.c
> /tmp/test.c:9: warning: No description found for parameter 'this_is_a_very_long_struct_name_so_need_to_break_for_thevery_long_member_name'
> /tmp/test.c:9: warning: Excess struct/union/enum/typedef member 'very_long_member_name' description in 'something'
>
>
> .. c:type:: struct something
>
>
> **Definition**
>
> ::
>
> struct something {
> };
>
> **Members**
>
>
>
> Clearly, the code that strips trailing and leading whitespace (in
> process_proto_type) is a bit *too* eager to do so, but so far I haven't
> found anything that makes it work.
>
> Anyone have any thoughts?
A trivial "fix" would be to use just one line for the struct field :-)
-
The logic that handle structs is at sub dump_struct() function at
kernel-doc, with is called by dump_declaration().
I added some debug prints at kernel-doc...
I guess the problem you're noticing is at process_proto_type():
$ ./scripts/kernel-doc -rst -internal /tmp/test.c
process_proto_type - original:struct something {
process_proto_type - parsed: struct something {
process_proto_type - original: struct this_is_a_very_long_struct_name_so_need_to_break_for_the
process_proto_type - parsed: struct this_is_a_very_long_struct_name_so_need_to_break_for_the
process_proto_type - original: very_long_member_name;
process_proto_type - parsed: very_long_member_name;
process_proto_type - original:};
process_proto_type - parsed: };
process_proto_type - to_dump: struct something {struct this_is_a_very_long_struct_name_so_need_to_break_for_thevery_long_member_name;};
dump_struct: struct something {struct this_is_a_very_long_struct_name_so_need_to_break_for_thevery_long_member_name;};
members: struct this_is_a_very_long_struct_name_so_need_to_break_for_thevery_long_member_name;
Basically, that while(1) loop there seems to be misinterpreting the line with "very_long_member_name;"
Thanks,
Mauro
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index a26a5f2dce39..55001278a2af 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -464,7 +464,7 @@ my $doc_com = '\s*\*\s*';
my $doc_com_body = '\s*\* ?';
my $doc_decl = $doc_com . '(\w+)';
# @params and a strictly limited set of supported section names
-my $doc_sect = $doc_com .
+my $doc_sect = $doc_com .
'\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
my $doc_content = $doc_com_body . '(.*)';
my $doc_block = $doc_com . 'DOC:\s*(.*)?';
@@ -2167,6 +2167,8 @@ sub dump_struct($$) {
my $nested;
if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
+
+printf("dump_struct: $x\n");
#my $decl_type = $1;
$declaration_name = $2;
my $members = $3;
@@ -2190,6 +2192,9 @@ sub dump_struct($$) {
# replace DECLARE_BITMAP
$members =~ s/DECLARE_BITMAP\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
+printf("members: $members\n");
+
+
create_parameterlist($members, ';', $file);
check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
@@ -2751,6 +2756,8 @@ sub process_proto_type($$) {
my $x = shift;
my $file = shift;
+printf("process_proto_type - original:$x\n");
+
$x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
$x =~ s@^\s+@@gos; # strip leading spaces
$x =~ s@\s+$@@gos; # strip trailing spaces
@@ -2761,12 +2768,15 @@ sub process_proto_type($$) {
$x .= ";";
}
+printf("process_proto_type - parsed: $x\n");
+
while (1) {
if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
$prototype .= $1 . $2;
($2 eq '{') && $brcount++;
($2 eq '}') && $brcount--;
if (($2 eq ';') && ($brcount == 0)) {
+printf("process_proto_type - to_dump: $prototype\n");
dump_declaration($prototype, $file);
reset_state();
last;
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
