linux-kernel - Re: [PATCH 04/12] docs: kdoc: Centralize handling of the item section list

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <87jz4gyy7o.fsf@trenco.lwn.net>
Date: Thu, 10 Jul 2025 07:25:31 -0600
From: Jonathan Corbet <corbet@....net>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc: linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org, Akira Yokosawa
 <akiyks@...il.com>
Subject: Re: [PATCH 04/12] docs: kdoc: Centralize handling of the item
 section list

Mauro Carvalho Chehab <mchehab+huawei@...nel.org> writes:

> Em Wed,  2 Jul 2025 16:35:16 -0600
> Jonathan Corbet <corbet@....net> escreveu:
>
>> The section list always comes directly from the under-construction entry
>> and is used uniformly.  Formalize section handling in the KdocItem class,
>> and have output_declaration() load the sections directly from the entry,
>> eliminating a lot of duplicated, verbose parameters.
>> 
>> Signed-off-by: Jonathan Corbet <corbet@....net>
>> ---
>>  scripts/lib/kdoc/kdoc_item.py   |  8 ++++++++
>>  scripts/lib/kdoc/kdoc_output.py | 36 ++++++++++++---------------------
>>  scripts/lib/kdoc/kdoc_parser.py | 20 +++---------------
>>  3 files changed, 24 insertions(+), 40 deletions(-)
>> 
>> diff --git a/scripts/lib/kdoc/kdoc_item.py b/scripts/lib/kdoc/kdoc_item.py
>> index add2cc772fec..c8329019a219 100644
>> --- a/scripts/lib/kdoc/kdoc_item.py
>> +++ b/scripts/lib/kdoc/kdoc_item.py
>> @@ -9,6 +9,7 @@ class KdocItem:
>>          self.name = name
>>          self.type = type
>>          self.declaration_start_line = start_line
>> +        self.sections = self.sections_start_lines = { }
>
> Nitpicks:
> - to make coding-style uniform, please use "{}" without spaces;
> - Please place one statement per line, just like we (usually) do in Kernel. 

Sure, fine.

>   In this specific case, I strongly suspect that what you coded is not
>   implementing the semantics you want. See:
>
> 	1. are you creating a single dict and placing the same dict on two
> 	   variables?
>   or:
> 	2. are you initializing two different vars with their own empty
> 	   dict?
>
> The subsequent code assumes (2), but a quick check with python3 command
> line:

As you note, the subsequent code does *not* actually assume that; I know
the way Python semantics work :)  But I can separate the lines and make
things explicit.

Thanks,

jon