On Tue, Nov 12, 2024 at 12:18 PM Jonathan Corbet <corbet@xxxxxxx> wrote:
>
> anish kumar <yesanishhere@xxxxxxxxx> 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@xxxxxxxxx>
> > ---
> > 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
