linux-kernel - Re: [PATCH] docs: driver-model: generate kernel-doc for driver model using script

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: <CABCoZhCp0oCTXFx911ftkUhHzkg5wwTVJyNQ1yKMWsocuwJM9A@mail.gmail.com>
Date: Tue, 12 Nov 2024 13:41:17 -0800
From: anish kumar <yesanishhere@...il.com>
To: Jonathan Corbet <corbet@....net>
Cc: broonie@...nel.org, dlechner@...libre.com, u.kleine-koenig@...gutronix.de, 
	Jonathan.Cameron@...wei.com, pstanner@...hat.com, 
	linux-kernel@...r.kernel.org, linux-doc@...r.kernel.org
Subject: Re: [PATCH] docs: driver-model: generate kernel-doc for driver model
 using script

On Tue, Nov 12, 2024 at 12:18 PM Jonathan Corbet <corbet@....net> wrote:
>
> anish kumar <yesanishhere@...il.com> writes:
>
> > In commit 63dc355 ("remove the driver-model structures from the
> > documentation"), the kernel-doc text was removed, and users were
> > instructed to read the documentation directly from the source code.
> > However, using the kernel-doc script to extract and generate the
> > documentation is a better approach, as it ensures the documentation
> > remains in sync with the code. Additionally, it provides users with
> > a more convenient way to access the documentation without needing to
> > refer directly to the source code.
> >
> > This patch adds kernel-doc annotations for the driver model to
> > facilitate the use of the kernel-doc script.
> >
> > Signed-off-by: anish kumar <yesanishhere@...il.com>
> > ---
> >  Documentation/driver-api/driver-model/bus.rst    | 4 +++-
> >  Documentation/driver-api/driver-model/device.rst | 4 ++--
> >  Documentation/driver-api/driver-model/driver.rst | 3 ++-
> >  3 files changed, 7 insertions(+), 4 deletions(-)
>
> This does not work very well...
>
> Documentation/driver-api/driver-model/bus:8: ./include/linux/device/bus.h:3: WARNING: Duplicate C declaration, also defined at driver-api/infrastructure:3.
> Declaration is '.. c:struct:: bus_type'.
> WARNING: kernel-doc './scripts/kernel-doc -rst -enable-lineno -sphinx-version 7.2.6 -function struct -function device ./include/linux/device/device.h' failed with return code 1
> Documentation/driver-api/driver-model/driver:5: ./include/linux/device/driver.h:3: WARNING: Duplicate C declaration, also defined at driver-api/infrastructure:48.
> Declaration is '.. c:struct:: device_driver'.
>
> Please actually perform a documentation build and look at the results
> before sending patches.

I followed the steps, but unfortunately, the warning did not appear
in older kernels. I also couldn't find any mention of where to
download the source code for the patches in this directory.
It doesn't seem to be listed in the MAINTAINERS file. I think I can
use the latest mainline kernel for sending patches for this directory
where I can clearly see these warnings.

Additionally, I noticed that this api already appears in infrastructure.rst.
Given that, do you think it makes sense to continue pursuing this patch,
or should I modify it to reference the infrastructure.rst file instead?
Or, would it be better to drop the patch altogether?

Thanks for your guidance.
>
> Thanks,
>
> jon