Re: [RFC] scripts: kernel-doc: avoid warnings due to initial commented lines in file

On 10/3/21 11:49 am, Lukas Bulwahn wrote:

On Tue, Mar 9, 2021 at 10:24 PM Aditya [off-list ref] wrote:

quoted

On 9/3/21 7:00 pm, Markus Heiser wrote:

quoted

Am 09.03.21 um 13:53 schrieb Aditya Srivastava:

quoted

Starting commented lines in a file mostly contains comments describing
license, copyright or general information about the file.

E.g., in sound/pci/ctxfi/ctresource.c, initial comment lines describe
its copyright and other related file informations.

The opening comment mark /** is used for kernel-doc comments [1]

[1]
https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#how-to-format-kernel-doc-comments

Hi Markus!
That's true. But the content inside the comment does not follow
kernel-doc format.
For e.g., try running kernel-doc -none/man/rst on the above file in
the example("sound/pci/ctxfi/ctresource.c").
The starting 2-3 lines in files generally do not contain any
struct/enum/function, etc. declaration.

Aditya, can you provide a diff of the warnings over the whole kernel tree?

At the moment, your patch just implements ignoring the initial
comment, which probably is good for experimentation.

Alternatively, we could simply have a dedicated warning and then
ignore it or even warn and then parse it as-if.

In the "long run", we would probably want to fix all current files in
the repository by just replacing '/**' by '/*' and have kernel-doc
warn about this suspicious pattern, when new files appear (maybe even
configurable, but that is another feature to enable or disable certain
kernel-doc checks and warnings). I would certainly assist and
contribute to such a clean-up task.

I think the first step is to look at the diff, and see how many cases
really appear in the tree... then check how many patches throughout
the whole tree are required and if they are generally accepted.

Hi Lukas!
This is the diff of the warnings over kernel tree before and after
applying these changes.
There are 2 sections in this report:
1) for the warnings present before, but not after, and;
2) after but not before

The part (2) contains, for some cases, where the warning for "warning:
Incorrect use of kernel-doc format:" type has changed to "warning:
wrong kernel-doc identifier on line:" type.

The diff file can be found at:
https://github.com/AdityaSrivast/kernel-tasks/blob/master/random/kernel-doc/avoid_init_line_diff.txt


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