On Sat, Jan 23, 2021 at 8:44 AM Lukas Bulwahn <lukas.bulwahn@gmail.com> wrote:
>
> On Fri, Jan 22, 2021 at 10:27 PM Dwaipayan Ray <dwaipayanray1@gmail.com> wrote:
> >
> > Hi Lukas and all,
> > Recently while going through the warnings emitted by checkpatch,
> > the necessity of a verbose mode came up once again. Joe had
> > already suggested that a verbose mode would probably be worked
> > on.
> >
> > As for how that could be done, that leaves us at a couple of options.
> > Since writing verbose messages for all warnings aren't possible at once,
> > there can be an optional extension when emitting messages:
> >
> > Currently, a warning can be emitted by
> > WARN("TYPE", "Message")
> > which could be converted to say:
> > WARN('TYPE", "Message", "Verbose")
> >
> > Another way is to leave the original warning emitting syntax intact
> > and instead go for a dictionary for verbose messages:
> > our %dict = (
> > "TYPE1" => "Verbose",
> > "TYPE2" => "Verbose"
> > ...);
> >
> > Although this leaves us the ability to customize the verbose output
> > for each warning of a particular type.
> >
> > Which do you think would be best? Certainly more options might be
> > possible, so any new inputs will be nice as well!
> >
>
> I think any of the two approaches would work.
>
> But how about a completely different approach?
>
> The verbose message is really an explanation of why kernel developers
> think this rule should be followed (what is the history, what does it
> try to warn about, what are possible fixes, what are accepted
> deviations, ...).
>
> So, this should not be placed into the checkpatch.pl script itself,
> but into Documentation.
>
> checkpatch.pl would simply quickly parse the Documentation and present
> the content for the specific rules that were violated.
>
> Let's say this Documentation is in
> ./Documentation/tools/checkpatch.rst, and they contain subsections
> with labels/name with the TYPE identifier. Then when a warning of TYPE
> is relevant for a specific patch, you print the description from that
> one subsection.
>
> In checkpatch itself, you would only need a very generic mechanism then.
>

That sounds great to me!
Even I had it in mind but thought maybe checkpatch could be less
reliant on other
files. But this also solves our purpose for an external documentation
for checkpatch
rules, so its a kinda win win situation.

I think maybe we will need a special structure for the documentation file itself
but its certainly doable.

Do you think I should go on to propose this idea to Joe now?

Thanks,
Dwaipayan.