On 10/3/21 11:49 am, Lukas Bulwahn wrote: > On Tue, Mar 9, 2021 at 10:24 PM Aditya <yashsri421@xxxxxxxxx> 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
