Issues with kernel-doc

Issues with kernel-doc

[Aditya]

Hi Jonathan

I and Lukas have been using scripts/kernel-doc lately, and we have
noticed a few issues with the script.

Also, I have generated a detailed report of warnings and errors caused
by running kernel-doc -none on entire kernel tree. It can be found at:

Complete report:
https://github.com/AdityaSrivast/kernel-tasks/blob/master/random/kernel-doc/report.txt

Since this report is very large, I shortened it in less-common warning
and no warning versions of the report as well.

No warning:
https://github.com/AdityaSrivast/kernel-tasks/blob/master/random/kernel-doc/error_report.txt

Less common warnings:
https://github.com/AdityaSrivast/kernel-tasks/blob/master/random/kernel-doc/reduced_report.txt

These are the few issues that we noticed with the script:

Running kernel-doc on gcov/gcc_4_7.c,
"scripts/kernel-doc -none kernel/gcov/gcc_4_7.c", caused this error:

Use of uninitialized value $param in regexp compilation at
./scripts/kernel-doc line 1559, <IN_FILE> line 95.
Use of uninitialized value $actual in substitution (s///) at
./scripts/kernel-doc line 1523, <IN_FILE> line 95.
Use of uninitialized value $actual in substitution (s///) at
./scripts/kernel-doc line 1523, <IN_FILE> line 95.
Use of uninitialized value $param in substitution (s///) at
./scripts/kernel-doc line 1617, <IN_FILE> line 95.
Use of uninitialized value $param in hash element at
./scripts/kernel-doc line 1651, <IN_FILE> line 95.
Use of uninitialized value $param in pattern match (m//) at
./scripts/kernel-doc line 1651, <IN_FILE> line 95.
Use of uninitialized value $param in hash element at
./scripts/kernel-doc line 1652, <IN_FILE> line 95.
Use of uninitialized value $param in pattern match (m//) at
./scripts/kernel-doc line 1654, <IN_FILE> line 95.
Use of uninitialized value $param in concatenation (.) or string at
./scripts/kernel-doc line 1655, <IN_FILE> line 95.
Use of uninitialized value $param in hash element at
./scripts/kernel-doc line 1672, <IN_FILE> line 95.

In my investigation, I found that this occurs because of this
parameter in struct gcov_info:
"void (*merge[GCOV_COUNTERS])(gcov_type *, unsigned int)"

Here, regex match at Line 1556 in kernel-doc ($arg =~
m/[^\(]+\(\*?\s*([\w\.]*)\s*\)/;) was supposed to capture
"*merge[GCOV_COUNTERS]" as $param, but the regex does not take into
account the presence of square brackets, thus causing the error.

Similarly, running kernel-doc on include/linux/zstd.h, caused this error:
include/linux/zstd.h:153: error: Cannot parse struct or union!
include/linux/zstd.h:170: error: Cannot parse struct or union!
include/linux/zstd.h:180: error: Cannot parse struct or union!
include/linux/zstd.h:230: error: Cannot parse struct or union!
include/linux/zstd.h:273: error: Cannot parse struct or union!
include/linux/zstd.h:365: error: Cannot parse struct or union!
include/linux/zstd.h:421: error: Cannot parse struct or union!
include/linux/zstd.h:537: error: Cannot parse struct or union!
include/linux/zstd.h:682: error: Cannot parse struct or union!
include/linux/zstd.h:935: error: Cannot parse struct or union!

Certain struct definitions present in the file do not follow
the expected format for parsing. (struct struct_name)
For eg. for "struct ZSTD_compressionParameters", it is defined with
the help of typedef syntax, ie
typedef struct {
        unsigned int windowLog;
        unsigned int chainLog;
        unsigned int hashLog;
        unsigned int searchLog;
        unsigned int searchLength;
        unsigned int targetLength;
        ZSTD_strategy strategy;
} ZSTD_compressionParameters;

Here, although the compiler may not cause any error, kernel-doc emits
the error as it probably expects "struct struct_name" to occur together.

What do you think about these issues?
I want to fix these issues, if you agree that they need to be fixed.

There are a few more issues as well, apart from these two. But for the
start, I want to begin with Uninitialized $param errors.

Thanks
Aditya

[Linux-kernel-mentees] Issues with kernel-doc

[Aditya]

Hi Jonathan

I and Lukas have been using scripts/kernel-doc lately, and we have
noticed a few issues with the script.

Also, I have generated a detailed report of warnings and errors caused
by running kernel-doc -none on entire kernel tree. It can be found at:

Complete report:
https://github.com/AdityaSrivast/kernel-tasks/blob/master/random/kernel-doc/report.txt

Since this report is very large, I shortened it in less-common warning
and no warning versions of the report as well.

No warning:
https://github.com/AdityaSrivast/kernel-tasks/blob/master/random/kernel-doc/error_report.txt

Less common warnings:
https://github.com/AdityaSrivast/kernel-tasks/blob/master/random/kernel-doc/reduced_report.txt

These are the few issues that we noticed with the script:

Running kernel-doc on gcov/gcc_4_7.c,
"scripts/kernel-doc -none kernel/gcov/gcc_4_7.c", caused this error:

Use of uninitialized value $param in regexp compilation at
./scripts/kernel-doc line 1559, <IN_FILE> line 95.
Use of uninitialized value $actual in substitution (s///) at
./scripts/kernel-doc line 1523, <IN_FILE> line 95.
Use of uninitialized value $actual in substitution (s///) at
./scripts/kernel-doc line 1523, <IN_FILE> line 95.
Use of uninitialized value $param in substitution (s///) at
./scripts/kernel-doc line 1617, <IN_FILE> line 95.
Use of uninitialized value $param in hash element at
./scripts/kernel-doc line 1651, <IN_FILE> line 95.
Use of uninitialized value $param in pattern match (m//) at
./scripts/kernel-doc line 1651, <IN_FILE> line 95.
Use of uninitialized value $param in hash element at
./scripts/kernel-doc line 1652, <IN_FILE> line 95.
Use of uninitialized value $param in pattern match (m//) at
./scripts/kernel-doc line 1654, <IN_FILE> line 95.
Use of uninitialized value $param in concatenation (.) or string at
./scripts/kernel-doc line 1655, <IN_FILE> line 95.
Use of uninitialized value $param in hash element at
./scripts/kernel-doc line 1672, <IN_FILE> line 95.

In my investigation, I found that this occurs because of this
parameter in struct gcov_info:
"void (*merge[GCOV_COUNTERS])(gcov_type *, unsigned int)"

Here, regex match at Line 1556 in kernel-doc ($arg =~
m/[^\(]+\(\*?\s*([\w\.]*)\s*\)/;) was supposed to capture
"*merge[GCOV_COUNTERS]" as $param, but the regex does not take into
account the presence of square brackets, thus causing the error.

Similarly, running kernel-doc on include/linux/zstd.h, caused this error:
include/linux/zstd.h:153: error: Cannot parse struct or union!
include/linux/zstd.h:170: error: Cannot parse struct or union!
include/linux/zstd.h:180: error: Cannot parse struct or union!
include/linux/zstd.h:230: error: Cannot parse struct or union!
include/linux/zstd.h:273: error: Cannot parse struct or union!
include/linux/zstd.h:365: error: Cannot parse struct or union!
include/linux/zstd.h:421: error: Cannot parse struct or union!
include/linux/zstd.h:537: error: Cannot parse struct or union!
include/linux/zstd.h:682: error: Cannot parse struct or union!
include/linux/zstd.h:935: error: Cannot parse struct or union!

Certain struct definitions present in the file do not follow
the expected format for parsing. (struct struct_name)
For eg. for "struct ZSTD_compressionParameters", it is defined with
the help of typedef syntax, ie
typedef struct {
        unsigned int windowLog;
        unsigned int chainLog;
        unsigned int hashLog;
        unsigned int searchLog;
        unsigned int searchLength;
        unsigned int targetLength;
        ZSTD_strategy strategy;
} ZSTD_compressionParameters;

Here, although the compiler may not cause any error, kernel-doc emits
the error as it probably expects "struct struct_name" to occur together.

What do you think about these issues?
I want to fix these issues, if you agree that they need to be fixed.

There are a few more issues as well, apart from these two. But for the
start, I want to begin with Uninitialized $param errors.

Thanks
Aditya
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

Re: Issues with kernel-doc

[Jonathan Corbet]

Aditya <yashsri421@gmail.com> writes:

> Here, although the compiler may not cause any error, kernel-doc emits
> the error as it probably expects "struct struct_name" to occur together.
>
> What do you think about these issues?
> I want to fix these issues, if you agree that they need to be fixed.
>
> There are a few more issues as well, apart from these two. But for the
> start, I want to begin with Uninitialized $param errors.

There is no need to ask permission before sending bug fixes!  I would be
more than happy to receive them.

Thanks,

jon

Re: [Linux-kernel-mentees] Issues with kernel-doc

[Jonathan Corbet]

Aditya <yashsri421@gmail.com> writes:

> Here, although the compiler may not cause any error, kernel-doc emits
> the error as it probably expects "struct struct_name" to occur together.
>
> What do you think about these issues?
> I want to fix these issues, if you agree that they need to be fixed.
>
> There are a few more issues as well, apart from these two. But for the
> start, I want to begin with Uninitialized $param errors.

There is no need to ask permission before sending bug fixes!  I would be
more than happy to receive them.

Thanks,

jon
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees