[PATCH 0/2] docs: interconnect: Improve API documentation coverage

[PATCH 0/2] docs: interconnect: Improve API documentation coverage

[Kuan-Wei Chiu]

Improve the generic interconnect subsystem documentation by including
the existing kernel-doc comments from the source files.

Currently, the documentation only includes the provider data structures
from the header file and incorrectly states that consumer APIs are
undocumented.

Since drivers/interconnect/core.c contains a mix of both provider and
consumer APIs, this series uses the kernel-doc :functions: directive to
properly separate and document them in their respective sections.

Kuan-Wei Chiu (2):
  docs: interconnect: Add provider APIs to documentation
  docs: interconnect: Document consumer APIs and drop outdated text

 Documentation/driver-api/interconnect.rst | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

-- 
2.53.0.851.ga537e3e6e9-goog

[PATCH 1/2] docs: interconnect: Add provider APIs to documentation

[Kuan-Wei Chiu]

The "Interconnect providers" section currently only includes data
structures from include/linux/interconnect-provider.h.

Include drivers/interconnect/core.c to extract provider-specific
API documentation. The :functions: directive is used to prevent
mixing with consumer APIs.

Signed-off-by: Kuan-Wei Chiu <visitorckw@gmail.com>
---
 Documentation/driver-api/interconnect.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/driver-api/interconnect.rst b/Documentation/driver-api/interconnect.rst
index a92d0f277a1f..cf7a83f8c953 100644
--- a/Documentation/driver-api/interconnect.rst
+++ b/Documentation/driver-api/interconnect.rst
@@ -84,6 +84,12 @@ be registered with the interconnect provider core.
 
 .. kernel-doc:: include/linux/interconnect-provider.h
 
+.. kernel-doc:: drivers/interconnect/core.c
+   :functions: icc_provider_init icc_provider_register icc_provider_deregister
+               icc_node_create icc_node_create_dyn icc_node_destroy
+               icc_node_add icc_node_del icc_nodes_remove icc_node_set_name
+               icc_link_create icc_link_nodes
+
 Interconnect consumers
 ----------------------
 
-- 
2.53.0.851.ga537e3e6e9-goog

[PATCH 2/2] docs: interconnect: Document consumer APIs and drop outdated text

[Kuan-Wei Chiu]

The documentation currently states that consumer interfaces are not
documented, which is no longer true.

Remove the outdated claim and include the existing kernel-doc from
drivers/interconnect/core.c (filtered for consumer APIs) and
drivers/interconnect/bulk.c.

Signed-off-by: Kuan-Wei Chiu <visitorckw@gmail.com>
---
 Documentation/driver-api/interconnect.rst | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/Documentation/driver-api/interconnect.rst b/Documentation/driver-api/interconnect.rst
index cf7a83f8c953..cebb77b49d8d 100644
--- a/Documentation/driver-api/interconnect.rst
+++ b/Documentation/driver-api/interconnect.rst
@@ -95,8 +95,14 @@ Interconnect consumers
 
 Interconnect consumers are the clients which use the interconnect APIs to
 get paths between endpoints and set their bandwidth/latency/QoS requirements
-for these interconnect paths.  These interfaces are not currently
-documented.
+for these interconnect paths.
+
+.. kernel-doc:: drivers/interconnect/core.c
+   :functions: devm_of_icc_get of_icc_get_by_index of_icc_get icc_get
+               icc_put icc_enable icc_disable icc_set_bw icc_set_tag
+               icc_get_name
+
+.. kernel-doc:: drivers/interconnect/bulk.c
 
 Interconnect debugfs interfaces
 -------------------------------
-- 
2.53.0.851.ga537e3e6e9-goog

Re: [PATCH 0/2] docs: interconnect: Improve API documentation coverage

[Jonathan Corbet]

Kuan-Wei Chiu <visitorckw@gmail.com> writes:

> Improve the generic interconnect subsystem documentation by including
> the existing kernel-doc comments from the source files.
>
> Currently, the documentation only includes the provider data structures
> from the header file and incorrectly states that consumer APIs are
> undocumented.
>
> Since drivers/interconnect/core.c contains a mix of both provider and
> consumer APIs, this series uses the kernel-doc :functions: directive to
> properly separate and document them in their respective sections.
>
> Kuan-Wei Chiu (2):
>   docs: interconnect: Add provider APIs to documentation
>   docs: interconnect: Document consumer APIs and drop outdated text
>
>  Documentation/driver-api/interconnect.rst | 16 ++++++++++++++--
>  1 file changed, 14 insertions(+), 2 deletions(-)

Series applied, thanks.

jon