[Linux-kernel-mentees] Regarding checkpatch docs

[Lukas Bulwahn]

On Thu, Feb 4, 2021 at 9:46 AM Dwaipayan Ray <dwaipayanray1 at gmail.com> wrote:
>
> On Thu, Feb 4, 2021 at 12:43 PM Lukas Bulwahn <lukas.bulwahn at gmail.com> wrote:
> >
> > On Thu, Feb 4, 2021 at 7:25 AM Dwaipayan Ray <dwaipayanray1 at gmail.com> wrote:
> > >
> > > Hi,
> > > I have been writing the checkpatch docs for a while now. As Joe mentioned,
> > > I am trying to write verbose descriptions for all the 214 types in checkpatch.
> > >
> >
> > In which order are you trying to create them?
> >
> > I would like to be involved in writing as well.
> >
> > E.g., how do we structure the 214 rules in the document? What are the
> > top-level chapters, sub-level sections for all different rules?
> >
> > Which should we start with? (Again, I think the checkpatch evaluation
> > can guide us to document the most important rules first.)
> >
>
> So I was trying to document all the types alphabetically. And arranging them
> in that format in the docs file.
>
> Basically, all these types come under the section Type descriptions, and all
> the entries (which are rst field lists), are sorted in alphabetical order.
>
> So the entries are something like:
> :ALLOC_ARRAY_ARGS:
>   The first argument for kcalloc or kmalloc_array should be the
>   number of elements. sizeof() as the first argument is generally
>   wrong.
>
> :ALLOC_SIZEOF_STRUCT:
>   The allocation style is bad.  In general for family of
>   allocation functions using sizeof() to get memory size,
>   p = alloc(sizeof(struct foo), ...)
>   should be:
>   p = alloc(sizeof(*p), ...)
>
> and so on...
>
> I haven't ordered them into sub sections yet. Do we write all the rules
> first so that the verbose mode is enabled, and then structure it later on?
>

Sure, you can do it that way as well. I just fear that you might get
stuck on a set of unimportant rules.

Try going through alphabetically, but do not be afraid to skip a rule
if you get stuck.

> Or do you prefer partitioning it into subsections first, and then writing
> the entries for that subsection? I haven't yet have a robust classification
> as I haven't gone through all the rules yet. Could you suggest something?
>

All good. Do it as you do.

I have an early (not yet robust) classification as well, but when you
do it independently once you are through all the rules, we have two
independent classifications.

Then, we can really compare and build one "perfect" classification by
combining the best from both. This will make the classification really
good to defend, because it is not just "a one-person initial
decision".

> > > How do I send it to you for review? Will a google docs file for the same work?
> > >
> >
> > Sure that works for me; you can also just send me a work-in-progress
> > patch queue (and I will apply it and add more patches on top) or
> > simply share a git repository on github.
> >
> > You can decide, I am perfectly fine with any way you choose.
> >
>
> Sure, then I will be uploading my repository onto github and we can work
> on a separate branch like "checkpatch"

Just send me the link and I pull it.

Lukas