LinuxLists.cc - [PATCH] Expose the bus kernel docs to the build docs.

2021-03-07 01:38:39

Subject: [PATCH] Expose the bus kernel docs to the build docs.

2021-03-07 01:49:28

Subject: Re: [PATCH] Expose the bus kernel docs to the build docs.

On Sat, Mar 06, 2021 at 05:33:01PM -0800, Wren Turkal wrote:
> Before, the bus type related APIs that were defined in the
> include/linux/device/bus.h were not referenced anywhere in the docs, so
> I linked it to the bus types api documentation.

I think this is a good thing to do.

> +++ b/Documentation/driver-api/driver-model/bus.rst
> @@ -144,3 +144,5 @@ sysfs directory using::
>
> int bus_create_file(struct bus_type *, struct bus_attribute *);
> void bus_remove_file(struct bus_type *, struct bus_attribute *);
> +
> +.. kernel-doc:: include/linux/device/bus.h

Do you want to put a heading in front of it? I did this in xarray.rst:

Functions and structures
========================

.. kernel-doc:: include/linux/xarray.h
.. kernel-doc:: lib/xarray.c

Also, I see that drivers/base/bus.c is included in
driver-api/infrastructure.rst, and I feel that they should probably be
included together?

2021-03-07 01:53:19

by Wren Turkal

[permalink] [raw]

Subject: Re: [PATCH] Expose the bus kernel docs to the build docs.

Thanks for the feedback. I will cut another patch in a sec.

On 3/6/21 5:44 PM, Matthew Wilcox wrote:
> Do you want to put a heading in front of it? I did this in xarray.rst:
>
> Functions and structures
> ========================
>
> .. kernel-doc:: include/linux/xarray.h
> .. kernel-doc:: lib/xarray.c
>
> Also, I see that drivers/base/bus.c is included in
> driver-api/infrastructure.rst, and I feel that they should probably be
> included together?

2021-03-07 03:19:46

by Wren Turkal

[permalink] [raw]

Subject: [PATCH v2] Expose the bus kernel docs to the build docs.

Before, the bus type related APIs that were defined in the
include/linux/device/bus.h were not referenced anywhere in the docs, so
I linked it to the bus types api documentation.

Signed-off-by: Wren Turkal <[email protected]>
---
Documentation/driver-api/driver-model/bus.rst | 8 ++++++++
Documentation/driver-api/infrastructure.rst | 3 +--
2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/Documentation/driver-api/driver-model/bus.rst b/Documentation/driver-api/driver-model/bus.rst
index 016b15a6e8ea..6bed459b87cc 100644
--- a/Documentation/driver-api/driver-model/bus.rst
+++ b/Documentation/driver-api/driver-model/bus.rst
@@ -1,3 +1,5 @@
+.. _bus_types:
+
=========
Bus Types
=========
@@ -144,3 +146,9 @@ sysfs directory using::

int bus_create_file(struct bus_type *, struct bus_attribute *);
void bus_remove_file(struct bus_type *, struct bus_attribute *);
+
+Fucntions and Structures
+========================
+
+.. kernel-doc:: include/linux/device/bus.h
+.. kernel-doc:: drivers/base/bus.c
diff --git a/Documentation/driver-api/infrastructure.rst b/Documentation/driver-api/infrastructure.rst
index 683bd460e222..eb2a2c9e3c0c 100644
--- a/Documentation/driver-api/infrastructure.rst
+++ b/Documentation/driver-api/infrastructure.rst
@@ -41,8 +41,7 @@ Device Drivers Base
.. kernel-doc:: drivers/base/platform.c
:export:

-.. kernel-doc:: drivers/base/bus.c
- :export:
+:ref:`bus_types`

Device Drivers DMA Management
-----------------------------
--
2.30.1

2021-03-07 03:35:07

by Matthew Wilcox

[permalink] [raw]

Subject: Re: [PATCH v2] Expose the bus kernel docs to the build docs.

On Sat, Mar 06, 2021 at 07:12:19PM -0800, Wren Turkal wrote:
> +Fucntions and Structures

Typo, but hold off on a v3 until someone weighs in with an opinion on
the rest of the patch.

2021-03-07 03:45:48

by Wren Turkal

[permalink] [raw]

Subject: Re: [PATCH v2] Expose the bus kernel docs to the build docs.

On 3/6/21 7:16 PM, Matthew Wilcox wrote:
> On Sat, Mar 06, 2021 at 07:12:19PM -0800, Wren Turkal wrote:
>> +Fucntions and Structures
>
> Typo, but hold off on a v3 until someone weighs in with an opinion on
> the rest of the patch.
>

Okay, I fixed the misspelling locally. Looking forward to addtional
feedback.

Thanks,
wt

2021-03-08 19:17:29

by Wren Turkal

[permalink] [raw]

Subject: [PATCH v3] Expose the bus kernel docs to the build docs.

Before, the bus type related APIs that were defined in the
include/linux/device/bus.h were not referenced anywhere in the docs, so
I linked it to the bus types api documentation.

Signed-off-by: Wren Turkal <[email protected]>
---
Documentation/driver-api/driver-model/bus.rst | 8 ++++++++
Documentation/driver-api/infrastructure.rst | 3 +--
2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/Documentation/driver-api/driver-model/bus.rst b/Documentation/driver-api/driver-model/bus.rst
index 016b15a6e8ea..c53b01e95fd9 100644
--- a/Documentation/driver-api/driver-model/bus.rst
+++ b/Documentation/driver-api/driver-model/bus.rst
@@ -1,3 +1,5 @@
+.. _bus_types:
+
=========
Bus Types
=========
@@ -144,3 +146,9 @@ sysfs directory using::

int bus_create_file(struct bus_type *, struct bus_attribute *);
void bus_remove_file(struct bus_type *, struct bus_attribute *);
+
+Functions and Structures
+========================
+
+.. kernel-doc:: include/linux/device/bus.h
+.. kernel-doc:: drivers/base/bus.c
diff --git a/Documentation/driver-api/infrastructure.rst b/Documentation/driver-api/infrastructure.rst
index 683bd460e222..eb2a2c9e3c0c 100644
--- a/Documentation/driver-api/infrastructure.rst
+++ b/Documentation/driver-api/infrastructure.rst
@@ -41,8 +41,7 @@ Device Drivers Base
.. kernel-doc:: drivers/base/platform.c
:export:

-.. kernel-doc:: drivers/base/bus.c
- :export:
+:ref:`bus_types`

Device Drivers DMA Management
-----------------------------
--
2.30.1

2021-03-12 18:56:00

by Wren Turkal

[permalink] [raw]

Subject: Re: [PATCH v3] Expose the bus kernel docs to the build docs.

Matthew,

I hate to bother you, but how do I know if this patch is acceptable or
not. I am not sure how this is tracked.

Thanks,
wt

On 3/8/21 11:14 AM, Wren Turkal wrote:
> Before, the bus type related APIs that were defined in the
> include/linux/device/bus.h were not referenced anywhere in the docs, so
> I linked it to the bus types api documentation.
>
> Signed-off-by: Wren Turkal <[email protected]>
> ---
> Documentation/driver-api/driver-model/bus.rst | 8 ++++++++
> Documentation/driver-api/infrastructure.rst | 3 +--
> 2 files changed, 9 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/driver-api/driver-model/bus.rst b/Documentation/driver-api/driver-model/bus.rst
> index 016b15a6e8ea..c53b01e95fd9 100644
> --- a/Documentation/driver-api/driver-model/bus.rst
> +++ b/Documentation/driver-api/driver-model/bus.rst
> @@ -1,3 +1,5 @@
> +.. _bus_types:
> +
> =========
> Bus Types
> =========
> @@ -144,3 +146,9 @@ sysfs directory using::
>
> int bus_create_file(struct bus_type *, struct bus_attribute *);
> void bus_remove_file(struct bus_type *, struct bus_attribute *);
> +
> +Functions and Structures
> +========================
> +
> +.. kernel-doc:: include/linux/device/bus.h
> +.. kernel-doc:: drivers/base/bus.c
> diff --git a/Documentation/driver-api/infrastructure.rst b/Documentation/driver-api/infrastructure.rst
> index 683bd460e222..eb2a2c9e3c0c 100644
> --- a/Documentation/driver-api/infrastructure.rst
> +++ b/Documentation/driver-api/infrastructure.rst
> @@ -41,8 +41,7 @@ Device Drivers Base
> .. kernel-doc:: drivers/base/platform.c
> :export:
>
> -.. kernel-doc:: drivers/base/bus.c
> - :export:
> +:ref:`bus_types`
>
> Device Drivers DMA Management
> -----------------------------
>

--
You're more amazing than you think! ymatyt.com

2021-03-15 21:22:38

by Jonathan Corbet

[permalink] [raw]

Subject: Re: [PATCH v3] Expose the bus kernel docs to the build docs.

Wren Turkal <[email protected]> writes:

> Before, the bus type related APIs that were defined in the
> include/linux/device/bus.h were not referenced anywhere in the docs, so
> I linked it to the bus types api documentation.

This should really be phrased in the imperative style as described in
Documentation/process/submitting-patches.rst. I wouldn't ordinarily
reject a patch just for that, but...

> Signed-off-by: Wren Turkal <[email protected]>
> ---
> Documentation/driver-api/driver-model/bus.rst | 8 ++++++++
> Documentation/driver-api/infrastructure.rst | 3 +--
> 2 files changed, 9 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/driver-api/driver-model/bus.rst b/Documentation/driver-api/driver-model/bus.rst
> index 016b15a6e8ea..c53b01e95fd9 100644
> --- a/Documentation/driver-api/driver-model/bus.rst
> +++ b/Documentation/driver-api/driver-model/bus.rst
> @@ -1,3 +1,5 @@
> +.. _bus_types:
> +
> =========
> Bus Types
> =========
> @@ -144,3 +146,9 @@ sysfs directory using::
>
> int bus_create_file(struct bus_type *, struct bus_attribute *);
> void bus_remove_file(struct bus_type *, struct bus_attribute *);
> +
> +Functions and Structures
> +========================
> +
> +.. kernel-doc:: include/linux/device/bus.h
> +.. kernel-doc:: drivers/base/bus.c
> diff --git a/Documentation/driver-api/infrastructure.rst b/Documentation/driver-api/infrastructure.rst
> index 683bd460e222..eb2a2c9e3c0c 100644
> --- a/Documentation/driver-api/infrastructure.rst
> +++ b/Documentation/driver-api/infrastructure.rst
> @@ -41,8 +41,7 @@ Device Drivers Base
> .. kernel-doc:: drivers/base/platform.c
> :export:
>
> -.. kernel-doc:: drivers/base/bus.c
> - :export:
> +:ref:`bus_types`

Rather than inserting labels and making explicit cross-references, it
seems better to just let automarkup do the work for you. So instead of
the above line, something like:

See also Documentation/driver-api/driver-model/bus.rst

Thanks,

jon