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

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

[Wren Turkal]

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 <wt@penguintechs.org>
---
 Documentation/driver-api/driver-model/bus.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/driver-api/driver-model/bus.rst b/Documentation/driver-api/driver-model/bus.rst
index 016b15a6e8ea..4cd237ded827 100644
--- a/Documentation/driver-api/driver-model/bus.rst
+++ 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
-- 
2.30.1

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

[Matthew Wilcox]

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?

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

[Wren Turkal]

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?

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

[Wren Turkal]

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 <wt@penguintechs.org>
---
 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

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

[Matthew Wilcox]

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.

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

[Wren Turkal]

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

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

[Wren Turkal]

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 <wt@penguintechs.org>
---
 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

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

[Wren Turkal]

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 <wt@penguintechs.org>
> ---
>   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

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

[Jonathan Corbet]

Wren Turkal <wt@penguintechs.org> 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 <wt@penguintechs.org>
> ---
>  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