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

[Aditya <yashsri421@gmail.com>]

On 10/3/21 11:49 am, Lukas Bulwahn wrote:
> On Tue, Mar 9, 2021 at 10:24 PM Aditya <yashsri421@gmail.com> wrote:
>>
>> On 9/3/21 7:00 pm, Markus Heiser wrote:
>>>
>>> Am 09.03.21 um 13:53 schrieb Aditya Srivastava:
>>>> 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