linux-kernel - Re: [PATCH] docs: Fix kernel-doc indentation errors in multiple drivers

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] [day] [month] [year] [list]

Message-ID: <d73bc572-5895-4b90-8b5c-72ae9c949559@infradead.org>
Date: Sat, 19 Jul 2025 17:14:48 -0700
From: Randy Dunlap <rdunlap@...radead.org>
To: Felipe Hernandez <luis.hernandez093@...il.com>,
 Bagas Sanjaya <bagasdotme@...il.com>
Cc: Pavel Pisa <pisa@....cvut.cz>, corbet@....net,
 alexandre.belloni@...tlin.com, ondrej.ille@...il.com, mkl@...gutronix.de,
 James.Bottomley@...senpartnership.com, martin.petersen@...cle.com,
 linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
 Martin Jeřábek <martin.jerabek01@...il.com>,
 Jiří Novák <jnovak@....cvut.cz>
Subject: Re: [PATCH] docs: Fix kernel-doc indentation errors in multiple
 drivers

Hi Felipe,

On 7/7/25 6:43 AM, Felipe Hernandez wrote:
> On Sun, Jul 6, 2025 at 8:37 PM Bagas Sanjaya <bagasdotme@...il.com> wrote:
>>
>> On Sat, Jul 05, 2025 at 02:36:45PM -0700, Randy Dunlap wrote:
>>> It needs something to turn True and False into a bullet list
>>> (non-numbered), as documented in Documentation/doc-guide/kernel-doc.rst:
>>>
>>>      So, in order to produce the desired line breaks, you need to use a
>>>      ReST list, e. g.::
>>>
>>>       * Return:
>>>       * * %0          - OK to runtime suspend the device
>>>       * * %-EBUSY     - Device should not be runtime suspended
>>>
>>>
>>>
>>> I don't see any of these kernel-doc warnings. I would guess that
>>> either Pavel or I am using some older/newer version of whatever
>>> software is causing this.
>>>
>>
>> I think Sphinx reported these warnings on docs-next tree.

They are actually docutils warnings. and I do see them now,
I had just overlooked them.

> 
> Hi,
> 
> I just wanted to follow up with the thread. I had inadvertently done a
> reply not reply all after the first series of feedback from Pavel and
> Randy. I agree with Randy in that the nested lists be updated to use
> ReST list syntax. I'm working on a v2 and spot checking the output.
> 
> For reference:
> I am running docutils (Docutils 0.21.2, Python 3.13.5, on linux)
> My branch was based on commit 50c8770a42faf8b1c7abe93e7c114337f580a97d
> (linux-next/master).
> The specific error(s):
> /home/linux/Documentation/networking/device_drivers/can/ctu/ctucanfd-driver:526:
> ./drivers/net/can/ctucanfd/ctucanfd_base.c:511: ERROR: Unexpected
> indentation. [docutils]
> 
> I apologize if I should've started this work using the docs-next tree.
> I wasn't aware of it at the moment and was utilizing linux-next.

The linux-next tree has these warnings in it. I often use it for patches.

Have you made a new version of the patch? I haven't seen it.

Thanks.
-- 
~Randy