[Linux-kernel-mentees] Investigating ./scripts/kernel-doc for third phase of mentorship

[Lukas Bulwahn]

Hi Aditya,


I have been using ./scripts/kernel-doc lately and noticed a few issues
with this script.
For the third phase, I expect you to investigate the issues on
./scripts/kernel-doc below, describe the issue to the kernel-doc
maintainer, and work on proper support for this parser in kernel-doc.

When running kernel-doc on these files below, you should observe these errors:

./scripts/kernel-doc -none kernel/gcov/gcc_4_7.c

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.


./scripts/kernel-doc -none include/linux/zstd.h

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!

Can you reproduce these issues?


Further, I would see that you can create two new features for kernel-doc:

- Support for warning types and configuration of build warning flags,
i.e., with -W command-line arguments and output as known for compilers
- Support of default arguments

Let us start with investigation of those issues in the files, though.
Then, we see how complicated it is to resolve those and discuss that
with the maintainer.


Best regards,

Lukas