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

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

[anish kumar]

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@gmail.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(-)

diff --git a/Documentation/driver-api/driver-model/bus.rst b/Documentation/driver-api/driver-model/bus.rst
index 9709ab62a468..15fb77fc69df 100644
--- a/Documentation/driver-api/driver-model/bus.rst
+++ b/Documentation/driver-api/driver-model/bus.rst
@@ -4,7 +4,9 @@ Bus Types
 
 Definition
 ~~~~~~~~~~
-See the kerneldoc for the struct bus_type.
+
+.. kernel-doc:: include/linux/device/bus.h
+    :identifiers: struct bus_type
 
 int bus_register(struct bus_type * bus);
 
diff --git a/Documentation/driver-api/driver-model/device.rst b/Documentation/driver-api/driver-model/device.rst
index 0833be568b06..14095770e80b 100644
--- a/Documentation/driver-api/driver-model/device.rst
+++ b/Documentation/driver-api/driver-model/device.rst
@@ -2,8 +2,8 @@
 The Basic Device Structure
 ==========================
 
-See the kerneldoc for the struct device.
-
+.. kernel-doc:: include/linux/device/device.h
+    :identifiers: struct device
 
 Programming Interface
 ~~~~~~~~~~~~~~~~~~~~~
diff --git a/Documentation/driver-api/driver-model/driver.rst b/Documentation/driver-api/driver-model/driver.rst
index 06f818b1d622..b5e8b00878ca 100644
--- a/Documentation/driver-api/driver-model/driver.rst
+++ b/Documentation/driver-api/driver-model/driver.rst
@@ -2,7 +2,8 @@
 Device Drivers
 ==============
 
-See the kerneldoc for the struct device_driver.
+.. kernel-doc:: include/linux/device/driver.h
+    :identifiers: struct device_driver
 
 Allocation
 ~~~~~~~~~~
-- 
2.39.3 (Apple Git-146)

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

[Jonathan Corbet]

anish kumar <yesanishhere@gmail.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@gmail.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.

Thanks,

jon

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

[anish kumar]

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