On Thu, Feb 4, 2021 at 9:46 AM Dwaipayan Ray [off-list ref] wrote:
On Thu, Feb 4, 2021 at 12:43 PM Lukas Bulwahn [off-list ref] wrote:
quoted
On Thu, Feb 4, 2021 at 7:25 AM Dwaipayan Ray [off-list ref] wrote:
quoted
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".
quoted
quoted
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
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees