[PATCH 0/8] dt: doc build improvements and kerneldoc addition

[PATCH 0/8] dt: doc build improvements and kerneldoc addition

[Rob Herring]

This series reorganizes the DT documentation and adds the DT API
kerneldoc to the documentation build.

It's based on the current DT for-next branch which has a series of
kerneldoc fixes from Lee Jones.

Cc: Frank Rowand <frowand.list@gmail.com>
Cc: Lee Jones <lee.jones@linaro.org>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org

Rob Herring (8):
  dt-bindings: Fix reference in submitting-patches.rst to the DT ABI doc
  docs: dt: writing-schema: Remove spurious indentation
  docs: dt: writing-schema: Include the example schema in the doc build
  docs: dt: Make 'Devicetree' wording more consistent
  docs: dt: Group DT docs into relevant sub-sections
  of: Fix kerneldoc output formatting
  of: Add missing 'Return' section in kerneldoc comments
  docs: dt: Add DT API documentation

 Documentation/devicetree/bindings/index.rst   |   7 +-
 .../bindings/submitting-patches.rst           |   4 +-
 .../{ => bindings}/writing-schema.rst         |  17 +-
 Documentation/devicetree/changesets.rst       |   8 +-
 .../devicetree/dynamic-resolution-notes.rst   |   8 +-
 Documentation/devicetree/index.rst            |  19 +-
 Documentation/devicetree/kernel-api.rst       |  57 ++++
 Documentation/devicetree/of_unittest.rst      |   6 +-
 Documentation/devicetree/overlay-notes.rst    |   8 +-
 Documentation/devicetree/usage-model.rst      |   8 +-
 drivers/of/base.c                             | 323 +++++++++---------
 drivers/of/dynamic.c                          |  19 +-
 drivers/of/fdt.c                              |  17 +-
 drivers/of/irq.c                              |  14 +-
 drivers/of/overlay.c                          |  16 +-
 drivers/of/platform.c                         |  10 +-
 drivers/of/property.c                         |  66 ++--
 include/linux/of.h                            |  63 ++--
 18 files changed, 395 insertions(+), 275 deletions(-)
 rename Documentation/devicetree/{ => bindings}/writing-schema.rst (95%)
 create mode 100644 Documentation/devicetree/kernel-api.rst

-- 
2.27.0

[PATCH 1/8] dt-bindings: Fix reference in submitting-patches.rst to the DT ABI doc

[Rob Herring]

submitting-patches.rst has a stale reference to ABI.txt. Fix this with a
proper rSt link.

Cc: Frank Rowand <frowand.list@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Rob Herring <robh@kernel.org>
---
 Documentation/devicetree/bindings/submitting-patches.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst
index 68129ff09967..42e86f978be2 100644
--- a/Documentation/devicetree/bindings/submitting-patches.rst
+++ b/Documentation/devicetree/bindings/submitting-patches.rst
@@ -84,7 +84,7 @@ II. For kernel maintainers
 III. Notes
 ==========
 
-  0) Please see ...bindings/ABI.txt for details regarding devicetree ABI.
+  0) Please see :doc:`ABI` for details regarding devicetree ABI.
 
   1) This document is intended as a general familiarization with the process as
      decided at the 2013 Kernel Summit.  When in doubt, the current word of the
-- 
2.27.0

Re: [PATCH 1/8] dt-bindings: Fix reference in submitting-patches.rst to the DT ABI doc

[Mauro Carvalho Chehab]

Em Thu, 25 Mar 2021 10:47:06 -0600
Rob Herring <robh@kernel.org> escreveu:

> submitting-patches.rst has a stale reference to ABI.txt. Fix this with a
> proper rSt link.
> 
> Cc: Frank Rowand <frowand.list@gmail.com>
> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
> Signed-off-by: Rob Herring <robh@kernel.org>

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

> ---
>  Documentation/devicetree/bindings/submitting-patches.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst
> index 68129ff09967..42e86f978be2 100644
> --- a/Documentation/devicetree/bindings/submitting-patches.rst
> +++ b/Documentation/devicetree/bindings/submitting-patches.rst
> @@ -84,7 +84,7 @@ II. For kernel maintainers
>  III. Notes
>  ==========
>  
> -  0) Please see ...bindings/ABI.txt for details regarding devicetree ABI.
> +  0) Please see :doc:`ABI` for details regarding devicetree ABI.
>  
>    1) This document is intended as a general familiarization with the process as
>       decided at the 2013 Kernel Summit.  When in doubt, the current word of the



Thanks,
Mauro

[PATCH 2/8] docs: dt: writing-schema: Remove spurious indentation

[Rob Herring]

'allOf' and 'properties' have a leading space which causes them to be
indented in the doc output.

Cc: Frank Rowand <frowand.list@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Rob Herring <robh@kernel.org>
---
 Documentation/devicetree/writing-schema.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/writing-schema.rst
index 16f21e182ff6..03e279d8fd6a 100644
--- a/Documentation/devicetree/writing-schema.rst
+++ b/Documentation/devicetree/writing-schema.rst
@@ -46,12 +46,12 @@ select
   schema. By default without 'select', nodes are matched against their possible
   compatible string values or node name. Most bindings should not need select.
 
- allOf
+allOf
   Optional. A list of other schemas to include. This is used to
   include other schemas the binding conforms to. This may be schemas for a
   particular class of devices such as I2C or SPI controllers.
 
- properties
+properties
   A set of sub-schema defining all the DT properties for the
   binding. The exact schema syntax depends on whether properties are known,
   common properties (e.g. 'interrupts') or are binding/vendor specific properties.
-- 
2.27.0

Re: [PATCH 2/8] docs: dt: writing-schema: Remove spurious indentation

[Mauro Carvalho Chehab]

Em Thu, 25 Mar 2021 10:47:07 -0600
Rob Herring <robh@kernel.org> escreveu:

> 'allOf' and 'properties' have a leading space which causes them to be
> indented in the doc output.
> 
> Cc: Frank Rowand <frowand.list@gmail.com>
> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

> Signed-off-by: Rob Herring <robh@kernel.org>
> ---
>  Documentation/devicetree/writing-schema.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/writing-schema.rst
> index 16f21e182ff6..03e279d8fd6a 100644
> --- a/Documentation/devicetree/writing-schema.rst
> +++ b/Documentation/devicetree/writing-schema.rst
> @@ -46,12 +46,12 @@ select
>    schema. By default without 'select', nodes are matched against their possible
>    compatible string values or node name. Most bindings should not need select.
>  
> - allOf
> +allOf
>    Optional. A list of other schemas to include. This is used to
>    include other schemas the binding conforms to. This may be schemas for a
>    particular class of devices such as I2C or SPI controllers.
>  
> - properties
> +properties
>    A set of sub-schema defining all the DT properties for the
>    binding. The exact schema syntax depends on whether properties are known,
>    common properties (e.g. 'interrupts') or are binding/vendor specific properties.



Thanks,
Mauro

[PATCH 3/8] docs: dt: writing-schema: Include the example schema in the doc build

[Rob Herring]

The example-schema.yaml file serves as documentation, so let's include it
from writing-schema.rst.

Cc: Frank Rowand <frowand.list@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Rob Herring <robh@kernel.org>
---
 Documentation/devicetree/writing-schema.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/writing-schema.rst
index 03e279d8fd6a..be14dbed6081 100644
--- a/Documentation/devicetree/writing-schema.rst
+++ b/Documentation/devicetree/writing-schema.rst
@@ -8,6 +8,8 @@ written in a JSON compatible subset of YAML. YAML is used instead of JSON as it
 is considered more human readable and has some advantages such as allowing
 comments (Prefixed with '#').
 
+Also see :ref:`example-schema`.
+
 Schema Contents
 ---------------
 
@@ -170,3 +172,12 @@ json-schema Resources
 `JSON-Schema Specifications <http://json-schema.org/>`_
 
 `Using JSON Schema Book <http://usingjsonschema.com/>`_
+
+.. _example-schema:
+
+Annotated Example Schema
+------------------------
+
+Also available as a separate file: :download:`example-schema.yaml`
+
+.. literalinclude:: example-schema.yaml
-- 
2.27.0

Re: [PATCH 3/8] docs: dt: writing-schema: Include the example schema in the doc build

[Mauro Carvalho Chehab]

Em Thu, 25 Mar 2021 10:47:08 -0600
Rob Herring <robh@kernel.org> escreveu:

> The example-schema.yaml file serves as documentation, so let's include it
> from writing-schema.rst.
> 
> Cc: Frank Rowand <frowand.list@gmail.com>
> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

> Signed-off-by: Rob Herring <robh@kernel.org>
> ---
>  Documentation/devicetree/writing-schema.rst | 11 +++++++++++
>  1 file changed, 11 insertions(+)
> 
> diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/writing-schema.rst
> index 03e279d8fd6a..be14dbed6081 100644
> --- a/Documentation/devicetree/writing-schema.rst
> +++ b/Documentation/devicetree/writing-schema.rst
> @@ -8,6 +8,8 @@ written in a JSON compatible subset of YAML. YAML is used instead of JSON as it
>  is considered more human readable and has some advantages such as allowing
>  comments (Prefixed with '#').
>  
> +Also see :ref:`example-schema`.
> +
>  Schema Contents
>  ---------------
>  
> @@ -170,3 +172,12 @@ json-schema Resources
>  `JSON-Schema Specifications <http://json-schema.org/>`_
>  
>  `Using JSON Schema Book <http://usingjsonschema.com/>`_
> +
> +.. _example-schema:
> +
> +Annotated Example Schema
> +------------------------
> +
> +Also available as a separate file: :download:`example-schema.yaml`
> +
> +.. literalinclude:: example-schema.yaml



Thanks,
Mauro

[PATCH 4/8] docs: dt: Make 'Devicetree' wording more consistent

[Rob Herring]

There's a variety of ways 'Devicetree' has been written. This is most
evident in the documentation build contents where we have 'Device Tree',
'DeviceTree', etc. The DT spec has somewhat standardized on
'Devicetree', so let's use that.

Cc: Frank Rowand <frowand.list@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Rob Herring <robh@kernel.org>
---
 Documentation/devicetree/bindings/submitting-patches.rst | 2 +-
 Documentation/devicetree/changesets.rst                  | 8 ++++----
 Documentation/devicetree/dynamic-resolution-notes.rst    | 8 ++++----
 Documentation/devicetree/index.rst                       | 2 +-
 Documentation/devicetree/of_unittest.rst                 | 6 +++---
 Documentation/devicetree/overlay-notes.rst               | 8 ++++----
 Documentation/devicetree/usage-model.rst                 | 8 ++++----
 Documentation/devicetree/writing-schema.rst              | 2 +-
 8 files changed, 22 insertions(+), 22 deletions(-)

diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst
index 42e86f978be2..51c459909575 100644
--- a/Documentation/devicetree/bindings/submitting-patches.rst
+++ b/Documentation/devicetree/bindings/submitting-patches.rst
@@ -1,7 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0
 
 ==========================================
-Submitting devicetree (DT) binding patches
+Submitting Devicetree (DT) binding patches
 ==========================================
 
 I. For patch submitters
diff --git a/Documentation/devicetree/changesets.rst b/Documentation/devicetree/changesets.rst
index c7fd8cd6a270..2091468d4837 100644
--- a/Documentation/devicetree/changesets.rst
+++ b/Documentation/devicetree/changesets.rst
@@ -1,10 +1,10 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-=============
-DT Changesets
-=============
+=====================
+Devicetree Changesets
+=====================
 
-A DT changeset is a method which allows one to apply changes
+A Devicetree changeset is a method which allows one to apply changes
 in the live tree in such a way that either the full set of changes
 will be applied, or none of them will be. If an error occurs partway
 through applying the changeset, then the tree will be rolled back to the
diff --git a/Documentation/devicetree/dynamic-resolution-notes.rst b/Documentation/devicetree/dynamic-resolution-notes.rst
index 570b7e1f39eb..f81ad8daa36f 100644
--- a/Documentation/devicetree/dynamic-resolution-notes.rst
+++ b/Documentation/devicetree/dynamic-resolution-notes.rst
@@ -1,11 +1,11 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-==================================
-Device Tree Dynamic Resolver Notes
-==================================
+=================================
+Devicetree Dynamic Resolver Notes
+=================================
 
 This document describes the implementation of the in-kernel
-Device Tree resolver, residing in drivers/of/resolver.c
+DeviceTree resolver, residing in drivers/of/resolver.c
 
 How the resolver works
 ----------------------
diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
index 54026763916d..32509e8de8da 100644
--- a/Documentation/devicetree/index.rst
+++ b/Documentation/devicetree/index.rst
@@ -1,7 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0
 
 =============================
-Open Firmware and Device Tree
+Open Firmware and Devicetree
 =============================
 
 .. toctree::
diff --git a/Documentation/devicetree/of_unittest.rst b/Documentation/devicetree/of_unittest.rst
index dea05214f3ad..2afe41a37148 100644
--- a/Documentation/devicetree/of_unittest.rst
+++ b/Documentation/devicetree/of_unittest.rst
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-==================================
-Open Firmware Device Tree Unittest
-==================================
+=================================
+Open Firmware Devicetree Unittest
+=================================
 
 Author: Gaurav Minocha <gaurav.minocha.os@gmail.com>
 
diff --git a/Documentation/devicetree/overlay-notes.rst b/Documentation/devicetree/overlay-notes.rst
index c67cc676bbd2..b2b8db765b8c 100644
--- a/Documentation/devicetree/overlay-notes.rst
+++ b/Documentation/devicetree/overlay-notes.rst
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-=========================
-Device Tree Overlay Notes
-=========================
+========================
+Devicetree Overlay Notes
+========================
 
 This document describes the implementation of the in-kernel
 device tree overlay functionality residing in drivers/of/overlay.c and is a
@@ -11,7 +11,7 @@ companion document to Documentation/devicetree/dynamic-resolution-notes.rst[1]
 How overlays work
 -----------------
 
-A Device Tree's overlay purpose is to modify the kernel's live tree, and
+A Devicetree's overlay purpose is to modify the kernel's live tree, and
 have the modification affecting the state of the kernel in a way that
 is reflecting the changes.
 Since the kernel mainly deals with devices, any new device node that result
diff --git a/Documentation/devicetree/usage-model.rst b/Documentation/devicetree/usage-model.rst
index 1eb83496ca1e..b6a287955ee5 100644
--- a/Documentation/devicetree/usage-model.rst
+++ b/Documentation/devicetree/usage-model.rst
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-=========================
-Linux and the Device Tree
-=========================
+========================
+Linux and the Devicetree
+========================
 
 The Linux usage model for device tree data
 
@@ -14,7 +14,7 @@ at devicetree.org\ [1]_.
 
 .. [1] https://www.devicetree.org/specifications/
 
-The "Open Firmware Device Tree", or simply Device Tree (DT), is a data
+The "Open Firmware Device Tree", or simply Devicetree (DT), is a data
 structure and language for describing hardware.  More specifically, it
 is a description of hardware that is readable by an operating system
 so that the operating system doesn't need to hard code details of the
diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/writing-schema.rst
index be14dbed6081..23d6579aea2c 100644
--- a/Documentation/devicetree/writing-schema.rst
+++ b/Documentation/devicetree/writing-schema.rst
@@ -1,6 +1,6 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-Writing DeviceTree Bindings in json-schema
+Writing Devicetree Bindings in json-schema
 ==========================================
 
 Devicetree bindings are written using json-schema vocabulary. Schema files are
-- 
2.27.0

Re: [PATCH 4/8] docs: dt: Make 'Devicetree' wording more consistent

[Mauro Carvalho Chehab]

Em Thu, 25 Mar 2021 10:47:09 -0600
Rob Herring <robh@kernel.org> escreveu:

> There's a variety of ways 'Devicetree' has been written. This is most
> evident in the documentation build contents where we have 'Device Tree',
> 'DeviceTree', etc. The DT spec has somewhat standardized on
> 'Devicetree', so let's use that.
> 
> Cc: Frank Rowand <frowand.list@gmail.com>
> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
> Signed-off-by: Rob Herring <robh@kernel.org>
> ---
>  Documentation/devicetree/bindings/submitting-patches.rst | 2 +-
>  Documentation/devicetree/changesets.rst                  | 8 ++++----
>  Documentation/devicetree/dynamic-resolution-notes.rst    | 8 ++++----
>  Documentation/devicetree/index.rst                       | 2 +-
>  Documentation/devicetree/of_unittest.rst                 | 6 +++---
>  Documentation/devicetree/overlay-notes.rst               | 8 ++++----
>  Documentation/devicetree/usage-model.rst                 | 8 ++++----
>  Documentation/devicetree/writing-schema.rst              | 2 +-
>  8 files changed, 22 insertions(+), 22 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst
> index 42e86f978be2..51c459909575 100644
> --- a/Documentation/devicetree/bindings/submitting-patches.rst
> +++ b/Documentation/devicetree/bindings/submitting-patches.rst
> @@ -1,7 +1,7 @@
>  .. SPDX-License-Identifier: GPL-2.0
>  
>  ==========================================
> -Submitting devicetree (DT) binding patches
> +Submitting Devicetree (DT) binding patches
>  ==========================================
>  
>  I. For patch submitters
> diff --git a/Documentation/devicetree/changesets.rst b/Documentation/devicetree/changesets.rst
> index c7fd8cd6a270..2091468d4837 100644
> --- a/Documentation/devicetree/changesets.rst
> +++ b/Documentation/devicetree/changesets.rst
> @@ -1,10 +1,10 @@
>  .. SPDX-License-Identifier: GPL-2.0
>  
> -=============
> -DT Changesets
> -=============
> +=====================
> +Devicetree Changesets
> +=====================
>  
> -A DT changeset is a method which allows one to apply changes
> +A Devicetree changeset is a method which allows one to apply changes
>  in the live tree in such a way that either the full set of changes
>  will be applied, or none of them will be. If an error occurs partway
>  through applying the changeset, then the tree will be rolled back to the
> diff --git a/Documentation/devicetree/dynamic-resolution-notes.rst b/Documentation/devicetree/dynamic-resolution-notes.rst
> index 570b7e1f39eb..f81ad8daa36f 100644
> --- a/Documentation/devicetree/dynamic-resolution-notes.rst
> +++ b/Documentation/devicetree/dynamic-resolution-notes.rst
> @@ -1,11 +1,11 @@
>  .. SPDX-License-Identifier: GPL-2.0
>  
> -==================================
> -Device Tree Dynamic Resolver Notes
> -==================================
> +=================================
> +Devicetree Dynamic Resolver Notes
> +=================================
>  
>  This document describes the implementation of the in-kernel
> -Device Tree resolver, residing in drivers/of/resolver.c
> +DeviceTree resolver, residing in drivers/of/resolver.c

DeviceTree -> Devicetree.

The rest looks ok to me.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

>  
>  How the resolver works
>  ----------------------
> diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
> index 54026763916d..32509e8de8da 100644
> --- a/Documentation/devicetree/index.rst
> +++ b/Documentation/devicetree/index.rst
> @@ -1,7 +1,7 @@
>  .. SPDX-License-Identifier: GPL-2.0
>  
>  =============================
> -Open Firmware and Device Tree
> +Open Firmware and Devicetree
>  =============================
>  
>  .. toctree::
> diff --git a/Documentation/devicetree/of_unittest.rst b/Documentation/devicetree/of_unittest.rst
> index dea05214f3ad..2afe41a37148 100644
> --- a/Documentation/devicetree/of_unittest.rst
> +++ b/Documentation/devicetree/of_unittest.rst
> @@ -1,8 +1,8 @@
>  .. SPDX-License-Identifier: GPL-2.0
>  
> -==================================
> -Open Firmware Device Tree Unittest
> -==================================
> +=================================
> +Open Firmware Devicetree Unittest
> +=================================
>  
>  Author: Gaurav Minocha <gaurav.minocha.os@gmail.com>
>  
> diff --git a/Documentation/devicetree/overlay-notes.rst b/Documentation/devicetree/overlay-notes.rst
> index c67cc676bbd2..b2b8db765b8c 100644
> --- a/Documentation/devicetree/overlay-notes.rst
> +++ b/Documentation/devicetree/overlay-notes.rst
> @@ -1,8 +1,8 @@
>  .. SPDX-License-Identifier: GPL-2.0
>  
> -=========================
> -Device Tree Overlay Notes
> -=========================
> +========================
> +Devicetree Overlay Notes
> +========================
>  
>  This document describes the implementation of the in-kernel
>  device tree overlay functionality residing in drivers/of/overlay.c and is a
> @@ -11,7 +11,7 @@ companion document to Documentation/devicetree/dynamic-resolution-notes.rst[1]
>  How overlays work
>  -----------------
>  
> -A Device Tree's overlay purpose is to modify the kernel's live tree, and
> +A Devicetree's overlay purpose is to modify the kernel's live tree, and
>  have the modification affecting the state of the kernel in a way that
>  is reflecting the changes.
>  Since the kernel mainly deals with devices, any new device node that result
> diff --git a/Documentation/devicetree/usage-model.rst b/Documentation/devicetree/usage-model.rst
> index 1eb83496ca1e..b6a287955ee5 100644
> --- a/Documentation/devicetree/usage-model.rst
> +++ b/Documentation/devicetree/usage-model.rst
> @@ -1,8 +1,8 @@
>  .. SPDX-License-Identifier: GPL-2.0
>  
> -=========================
> -Linux and the Device Tree
> -=========================
> +========================
> +Linux and the Devicetree
> +========================
>  
>  The Linux usage model for device tree data
>  
> @@ -14,7 +14,7 @@ at devicetree.org\ [1]_.
>  
>  .. [1] https://www.devicetree.org/specifications/
>  
> -The "Open Firmware Device Tree", or simply Device Tree (DT), is a data
> +The "Open Firmware Device Tree", or simply Devicetree (DT), is a data
>  structure and language for describing hardware.  More specifically, it
>  is a description of hardware that is readable by an operating system
>  so that the operating system doesn't need to hard code details of the
> diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/writing-schema.rst
> index be14dbed6081..23d6579aea2c 100644
> --- a/Documentation/devicetree/writing-schema.rst
> +++ b/Documentation/devicetree/writing-schema.rst
> @@ -1,6 +1,6 @@
>  .. SPDX-License-Identifier: GPL-2.0
>  
> -Writing DeviceTree Bindings in json-schema
> +Writing Devicetree Bindings in json-schema
>  ==========================================
>  
>  Devicetree bindings are written using json-schema vocabulary. Schema files are



Thanks,
Mauro

[PATCH 5/8] docs: dt: Group DT docs into relevant sub-sections

[Rob Herring]

The DT docs are currently all just lumped together in the doc build.
Let's organize the documents by kernel specifics, overlays and bindings.

As writing-schema.rst is about bindings, let's move it to the bindings
directory.

Cc: Frank Rowand <frowand.list@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Rob Herring <robh@kernel.org>
---
 Documentation/devicetree/bindings/index.rst      |  7 ++-----
 .../devicetree/{ => bindings}/writing-schema.rst |  0
 Documentation/devicetree/index.rst               | 16 ++++++++++++++--
 3 files changed, 16 insertions(+), 7 deletions(-)
 rename Documentation/devicetree/{ => bindings}/writing-schema.rst (100%)

diff --git a/Documentation/devicetree/bindings/index.rst b/Documentation/devicetree/bindings/index.rst
index 3837b17c234f..d9002a3a0abb 100644
--- a/Documentation/devicetree/bindings/index.rst
+++ b/Documentation/devicetree/bindings/index.rst
@@ -1,12 +1,9 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-===========
-Device Tree
-===========
-
 .. toctree::
    :maxdepth: 1
 
    ABI
-   submitting-patches
    writing-bindings
+   writing-schema
+   submitting-patches
diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst
similarity index 100%
rename from Documentation/devicetree/writing-schema.rst
rename to Documentation/devicetree/bindings/writing-schema.rst
diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
index 32509e8de8da..70b5dcdbcf07 100644
--- a/Documentation/devicetree/index.rst
+++ b/Documentation/devicetree/index.rst
@@ -4,14 +4,26 @@
 Open Firmware and Devicetree
 =============================
 
+Kernel Devicetree Usage
+=======================
 .. toctree::
    :maxdepth: 1
 
    usage-model
-   writing-schema
+   of_unittest
+
+Devicetree Overlays
+===================
+.. toctree::
+   :maxdepth: 1
+
    changesets
    dynamic-resolution-notes
-   of_unittest
    overlay-notes
 
+Devicetree Bindings
+===================
+.. toctree::
+   :maxdepth: 1
+
    bindings/index
-- 
2.27.0

Re: [PATCH 5/8] docs: dt: Group DT docs into relevant sub-sections

[Mauro Carvalho Chehab]

Em Thu, 25 Mar 2021 10:47:10 -0600
Rob Herring <robh@kernel.org> escreveu:

> The DT docs are currently all just lumped together in the doc build.
> Let's organize the documents by kernel specifics, overlays and bindings.
> 
> As writing-schema.rst is about bindings, let's move it to the bindings
> directory.
> 
> Cc: Frank Rowand <frowand.list@gmail.com>
> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

> Signed-off-by: Rob Herring <robh@kernel.org>
> ---
>  Documentation/devicetree/bindings/index.rst      |  7 ++-----
>  .../devicetree/{ => bindings}/writing-schema.rst |  0
>  Documentation/devicetree/index.rst               | 16 ++++++++++++++--
>  3 files changed, 16 insertions(+), 7 deletions(-)
>  rename Documentation/devicetree/{ => bindings}/writing-schema.rst (100%)
> 
> diff --git a/Documentation/devicetree/bindings/index.rst b/Documentation/devicetree/bindings/index.rst
> index 3837b17c234f..d9002a3a0abb 100644
> --- a/Documentation/devicetree/bindings/index.rst
> +++ b/Documentation/devicetree/bindings/index.rst
> @@ -1,12 +1,9 @@
>  .. SPDX-License-Identifier: GPL-2.0
>  
> -===========
> -Device Tree
> -===========
> -
>  .. toctree::
>     :maxdepth: 1
>  
>     ABI
> -   submitting-patches
>     writing-bindings
> +   writing-schema
> +   submitting-patches
> diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst
> similarity index 100%
> rename from Documentation/devicetree/writing-schema.rst
> rename to Documentation/devicetree/bindings/writing-schema.rst
> diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
> index 32509e8de8da..70b5dcdbcf07 100644
> --- a/Documentation/devicetree/index.rst
> +++ b/Documentation/devicetree/index.rst
> @@ -4,14 +4,26 @@
>  Open Firmware and Devicetree
>  =============================
>  
> +Kernel Devicetree Usage
> +=======================
>  .. toctree::
>     :maxdepth: 1
>  
>     usage-model
> -   writing-schema
> +   of_unittest
> +
> +Devicetree Overlays
> +===================
> +.. toctree::
> +   :maxdepth: 1
> +
>     changesets
>     dynamic-resolution-notes
> -   of_unittest
>     overlay-notes
>  
> +Devicetree Bindings
> +===================
> +.. toctree::
> +   :maxdepth: 1
> +
>     bindings/index



Thanks,
Mauro

[PATCH 6/8] of: Fix kerneldoc output formatting

[Rob Herring]

The indentation of the kerneldoc comments affects the output formatting.
Leading tabs in particular don't work, and sections need to be indented
under the section header.

The example snippets for DT source in the comments still have some
formatting issues, but there doesn't seem to be any way to do multi-line
literal blocks in kerneldoc.

Cc: Frank Rowand <frowand.list@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Rob Herring <robh@kernel.org>
---

Note the dts examples still cause warnings. I couldn't find any way to 
do a literal block and fix them. Minimally, there needs to be a way to 
escape ':' and not create sections:

Documentation/devicetree/kernel-api:11: ../drivers/of/base.c:1466: WARNING: Definition list ends without a blank line; unexpected unindent.
Documentation/devicetree/kernel-api:11: ../drivers/of/base.c:1470: WARNING: Definition list ends without a blank line; unexpected unindent.
Documentation/devicetree/kernel-api:11: ../drivers/of/base.c:1474: WARNING: Definition list ends without a blank line; unexpected unindent.
Documentation/devicetree/kernel-api:11: ../drivers/of/base.c:1517: WARNING: Definition list ends without a blank line; unexpected unindent.
Documentation/devicetree/kernel-api:11: ../drivers/of/base.c:1521: WARNING: Definition list ends without a blank line; unexpected unindent.
Documentation/devicetree/kernel-api:11: ../drivers/of/base.c:1526: WARNING: Unexpected indentation.
Documentation/devicetree/kernel-api:11: ../drivers/of/base.c:1528: WARNING: Block quote ends without a blank line; unexpected unindent.
Documentation/devicetree/kernel-api:11: ../drivers/of/base.c:1529: WARNING: Definition list ends without a blank line; unexpected unindent.
Documentation/devicetree/kernel-api:11: ../drivers/of/base.c:1533: WARNING: Definition list ends without a blank line; unexpected unindent.
Documentation/devicetree/kernel-api:11: ../drivers/of/base.c:1705: WARNING: Definition list ends without a blank line; unexpected unindent.

 drivers/of/base.c | 284 +++++++++++++++++++++++-----------------------
 drivers/of/fdt.c  |   9 +-
 2 files changed, 145 insertions(+), 148 deletions(-)

diff --git a/drivers/of/base.c b/drivers/of/base.c
index 457d1ec27300..b06bcb3f001a 100644
--- a/drivers/of/base.c
+++ b/drivers/of/base.c
@@ -651,11 +651,11 @@ bool of_device_is_big_endian(const struct device_node *device)
 EXPORT_SYMBOL(of_device_is_big_endian);
 
 /**
- *	of_get_parent - Get a node's parent if any
- *	@node:	Node to get parent
+ * of_get_parent - Get a node's parent if any
+ * @node:	Node to get parent
  *
- *	Returns a node pointer with refcount incremented, use
- *	of_node_put() on it when done.
+ * Return: A node pointer with refcount incremented, use
+ * of_node_put() on it when done.
  */
 struct device_node *of_get_parent(const struct device_node *node)
 {
@@ -673,15 +673,15 @@ struct device_node *of_get_parent(const struct device_node *node)
 EXPORT_SYMBOL(of_get_parent);
 
 /**
- *	of_get_next_parent - Iterate to a node's parent
- *	@node:	Node to get parent of
+ * of_get_next_parent - Iterate to a node's parent
+ * @node:	Node to get parent of
  *
- *	This is like of_get_parent() except that it drops the
- *	refcount on the passed node, making it suitable for iterating
- *	through a node's parents.
+ * This is like of_get_parent() except that it drops the
+ * refcount on the passed node, making it suitable for iterating
+ * through a node's parents.
  *
- *	Returns a node pointer with refcount incremented, use
- *	of_node_put() on it when done.
+ * Return: A node pointer with refcount incremented, use
+ * of_node_put() on it when done.
  */
 struct device_node *of_get_next_parent(struct device_node *node)
 {
@@ -719,13 +719,13 @@ static struct device_node *__of_get_next_child(const struct device_node *node,
 	     child = __of_get_next_child(parent, child))
 
 /**
- *	of_get_next_child - Iterate a node childs
- *	@node:	parent node
- *	@prev:	previous child of the parent node, or NULL to get first
+ * of_get_next_child - Iterate a node childs
+ * @node:	parent node
+ * @prev:	previous child of the parent node, or NULL to get first
  *
- *	Returns a node pointer with refcount incremented, use of_node_put() on
- *	it when done. Returns NULL when prev is the last child. Decrements the
- *	refcount of prev.
+ * Return: A node pointer with refcount incremented, use of_node_put() on
+ * it when done. Returns NULL when prev is the last child. Decrements the
+ * refcount of prev.
  */
 struct device_node *of_get_next_child(const struct device_node *node,
 	struct device_node *prev)
@@ -741,12 +741,12 @@ struct device_node *of_get_next_child(const struct device_node *node,
 EXPORT_SYMBOL(of_get_next_child);
 
 /**
- *	of_get_next_available_child - Find the next available child node
- *	@node:	parent node
- *	@prev:	previous child of the parent node, or NULL to get first
+ * of_get_next_available_child - Find the next available child node
+ * @node:	parent node
+ * @prev:	previous child of the parent node, or NULL to get first
  *
- *      This function is like of_get_next_child(), except that it
- *      automatically skips any disabled nodes (i.e. status = "disabled").
+ * This function is like of_get_next_child(), except that it
+ * automatically skips any disabled nodes (i.e. status = "disabled").
  */
 struct device_node *of_get_next_available_child(const struct device_node *node,
 	struct device_node *prev)
@@ -772,12 +772,12 @@ struct device_node *of_get_next_available_child(const struct device_node *node,
 EXPORT_SYMBOL(of_get_next_available_child);
 
 /**
- *	of_get_next_cpu_node - Iterate on cpu nodes
- *	@prev:	previous child of the /cpus node, or NULL to get first
+ * of_get_next_cpu_node - Iterate on cpu nodes
+ * @prev:	previous child of the /cpus node, or NULL to get first
  *
- *	Returns a cpu node pointer with refcount incremented, use of_node_put()
- *	on it when done. Returns NULL when prev is the last child. Decrements
- *	the refcount of prev.
+ * Return: A cpu node pointer with refcount incremented, use of_node_put()
+ * on it when done. Returns NULL when prev is the last child. Decrements
+ * the refcount of prev.
  */
 struct device_node *of_get_next_cpu_node(struct device_node *prev)
 {
@@ -834,15 +834,15 @@ struct device_node *of_get_compatible_child(const struct device_node *parent,
 EXPORT_SYMBOL(of_get_compatible_child);
 
 /**
- *	of_get_child_by_name - Find the child node by name for a given parent
- *	@node:	parent node
- *	@name:	child name to look for.
+ * of_get_child_by_name - Find the child node by name for a given parent
+ * @node:	parent node
+ * @name:	child name to look for.
  *
- *      This function looks for child node for given matching name
+ * This function looks for child node for given matching name
  *
- *	Returns a node pointer if found, with refcount incremented, use
- *	of_node_put() on it when done.
- *	Returns NULL if node is not found.
+ * Return: A node pointer if found, with refcount incremented, use
+ * of_node_put() on it when done.
+ * Returns NULL if node is not found.
  */
 struct device_node *of_get_child_by_name(const struct device_node *node,
 				const char *name)
@@ -893,22 +893,22 @@ struct device_node *__of_find_node_by_full_path(struct device_node *node,
 }
 
 /**
- *	of_find_node_opts_by_path - Find a node matching a full OF path
- *	@path: Either the full path to match, or if the path does not
- *	       start with '/', the name of a property of the /aliases
- *	       node (an alias).  In the case of an alias, the node
- *	       matching the alias' value will be returned.
- *	@opts: Address of a pointer into which to store the start of
- *	       an options string appended to the end of the path with
- *	       a ':' separator.
- *
- *	Valid paths:
- *		/foo/bar	Full path
- *		foo		Valid alias
- *		foo/bar		Valid alias + relative path
- *
- *	Returns a node pointer with refcount incremented, use
- *	of_node_put() on it when done.
+ * of_find_node_opts_by_path - Find a node matching a full OF path
+ * @path: Either the full path to match, or if the path does not
+ *       start with '/', the name of a property of the /aliases
+ *       node (an alias).  In the case of an alias, the node
+ *       matching the alias' value will be returned.
+ * @opts: Address of a pointer into which to store the start of
+ *       an options string appended to the end of the path with
+ *       a ':' separator.
+ *
+ * Valid paths:
+ *  * /foo/bar	Full path
+ *  * foo	Valid alias
+ *  * foo/bar	Valid alias + relative path
+ *
+ * Return: A node pointer with refcount incremented, use
+ * of_node_put() on it when done.
  */
 struct device_node *of_find_node_opts_by_path(const char *path, const char **opts)
 {
@@ -958,15 +958,15 @@ struct device_node *of_find_node_opts_by_path(const char *path, const char **opt
 EXPORT_SYMBOL(of_find_node_opts_by_path);
 
 /**
- *	of_find_node_by_name - Find a node by its "name" property
- *	@from:	The node to start searching from or NULL; the node
+ * of_find_node_by_name - Find a node by its "name" property
+ * @from:	The node to start searching from or NULL; the node
  *		you pass will not be searched, only the next one
  *		will. Typically, you pass what the previous call
  *		returned. of_node_put() will be called on @from.
- *	@name:	The name string to match against
+ * @name:	The name string to match against
  *
- *	Returns a node pointer with refcount incremented, use
- *	of_node_put() on it when done.
+ * Return: A node pointer with refcount incremented, use
+ * of_node_put() on it when done.
  */
 struct device_node *of_find_node_by_name(struct device_node *from,
 	const char *name)
@@ -985,16 +985,16 @@ struct device_node *of_find_node_by_name(struct device_node *from,
 EXPORT_SYMBOL(of_find_node_by_name);
 
 /**
- *	of_find_node_by_type - Find a node by its "device_type" property
- *	@from:	The node to start searching from, or NULL to start searching
+ * of_find_node_by_type - Find a node by its "device_type" property
+ * @from:	The node to start searching from, or NULL to start searching
  *		the entire device tree. The node you pass will not be
  *		searched, only the next one will; typically, you pass
  *		what the previous call returned. of_node_put() will be
  *		called on from for you.
- *	@type:	The type string to match against
+ * @type:	The type string to match against
  *
- *	Returns a node pointer with refcount incremented, use
- *	of_node_put() on it when done.
+ * Return: A node pointer with refcount incremented, use
+ * of_node_put() on it when done.
  */
 struct device_node *of_find_node_by_type(struct device_node *from,
 	const char *type)
@@ -1013,18 +1013,18 @@ struct device_node *of_find_node_by_type(struct device_node *from,
 EXPORT_SYMBOL(of_find_node_by_type);
 
 /**
- *	of_find_compatible_node - Find a node based on type and one of the
+ * of_find_compatible_node - Find a node based on type and one of the
  *                                tokens in its "compatible" property
- *	@from:		The node to start searching from or NULL, the node
- *			you pass will not be searched, only the next one
- *			will; typically, you pass what the previous call
- *			returned. of_node_put() will be called on it
- *	@type:		The type string to match "device_type" or NULL to ignore
- *	@compatible:	The string to match to one of the tokens in the device
- *			"compatible" list.
- *
- *	Returns a node pointer with refcount incremented, use
- *	of_node_put() on it when done.
+ * @from:	The node to start searching from or NULL, the node
+ *		you pass will not be searched, only the next one
+ *		will; typically, you pass what the previous call
+ *		returned. of_node_put() will be called on it
+ * @type:	The type string to match "device_type" or NULL to ignore
+ * @compatible:	The string to match to one of the tokens in the device
+ *		"compatible" list.
+ *
+ * Return: A node pointer with refcount incremented, use
+ * of_node_put() on it when done.
  */
 struct device_node *of_find_compatible_node(struct device_node *from,
 	const char *type, const char *compatible)
@@ -1044,16 +1044,16 @@ struct device_node *of_find_compatible_node(struct device_node *from,
 EXPORT_SYMBOL(of_find_compatible_node);
 
 /**
- *	of_find_node_with_property - Find a node which has a property with
- *                                   the given name.
- *	@from:		The node to start searching from or NULL, the node
- *			you pass will not be searched, only the next one
- *			will; typically, you pass what the previous call
- *			returned. of_node_put() will be called on it
- *	@prop_name:	The name of the property to look for.
- *
- *	Returns a node pointer with refcount incremented, use
- *	of_node_put() on it when done.
+ * of_find_node_with_property - Find a node which has a property with
+ *                              the given name.
+ * @from:	The node to start searching from or NULL, the node
+ *		you pass will not be searched, only the next one
+ *		will; typically, you pass what the previous call
+ *		returned. of_node_put() will be called on it
+ * @prop_name:	The name of the property to look for.
+ *
+ * Return: A node pointer with refcount incremented, use
+ * of_node_put() on it when done.
  */
 struct device_node *of_find_node_with_property(struct device_node *from,
 	const char *prop_name)
@@ -1102,10 +1102,10 @@ const struct of_device_id *__of_match_node(const struct of_device_id *matches,
 
 /**
  * of_match_node - Tell if a device_node has a matching of_match structure
- *	@matches:	array of of device match structures to search in
- *	@node:		the of device structure to match against
+ * @matches:	array of of device match structures to search in
+ * @node:	the of device structure to match against
  *
- *	Low level utility function used by device matching.
+ * Low level utility function used by device matching.
  */
 const struct of_device_id *of_match_node(const struct of_device_id *matches,
 					 const struct device_node *node)
@@ -1121,17 +1121,17 @@ const struct of_device_id *of_match_node(const struct of_device_id *matches,
 EXPORT_SYMBOL(of_match_node);
 
 /**
- *	of_find_matching_node_and_match - Find a node based on an of_device_id
- *					  match table.
- *	@from:		The node to start searching from or NULL, the node
- *			you pass will not be searched, only the next one
- *			will; typically, you pass what the previous call
- *			returned. of_node_put() will be called on it
- *	@matches:	array of of device match structures to search in
- *	@match:		Updated to point at the matches entry which matched
- *
- *	Returns a node pointer with refcount incremented, use
- *	of_node_put() on it when done.
+ * of_find_matching_node_and_match - Find a node based on an of_device_id
+ *				     match table.
+ * @from:	The node to start searching from or NULL, the node
+ *		you pass will not be searched, only the next one
+ *		will; typically, you pass what the previous call
+ *		returned. of_node_put() will be called on it
+ * @matches:	array of of device match structures to search in
+ * @match:	Updated to point at the matches entry which matched
+ *
+ * Return: A node pointer with refcount incremented, use
+ * of_node_put() on it when done.
  */
 struct device_node *of_find_matching_node_and_match(struct device_node *from,
 					const struct of_device_id *matches,
@@ -1462,20 +1462,20 @@ EXPORT_SYMBOL(of_parse_phandle);
  *
  * Example:
  *
- * phandle1: node1 {
+ *  phandle1: node1 {
  *	#list-cells = <2>;
- * }
+ *  };
  *
- * phandle2: node2 {
+ *  phandle2: node2 {
  *	#list-cells = <1>;
- * }
+ *  };
  *
- * node3 {
+ *  node3 {
  *	list = <&phandle1 1 2 &phandle2 3>;
- * }
+ *  };
  *
- * To get a device_node of the `node2' node you may call this:
- * of_parse_phandle_with_args(node3, "list", "#list-cells", 1, &args);
+ *  To get a device_node of the ``node2`` node you may call this:
+ *  of_parse_phandle_with_args(node3, "list", "#list-cells", 1, &args);
  */
 int of_parse_phandle_with_args(const struct device_node *np, const char *list_name,
 				const char *cells_name, int index,
@@ -1513,29 +1513,28 @@ EXPORT_SYMBOL(of_parse_phandle_with_args);
  * pointer.
  *
  * Example:
- *
- * phandle1: node1 {
- *	#list-cells = <2>;
- * }
- *
- * phandle2: node2 {
- *	#list-cells = <1>;
- * }
- *
- * phandle3: node3 {
- * 	#list-cells = <1>;
- * 	list-map = <0 &phandle2 3>,
- * 		   <1 &phandle2 2>,
- * 		   <2 &phandle1 5 1>;
- *	list-map-mask = <0x3>;
- * };
- *
- * node4 {
- *	list = <&phandle1 1 2 &phandle3 0>;
- * }
- *
- * To get a device_node of the `node2' node you may call this:
- * of_parse_phandle_with_args(node4, "list", "list", 1, &args);
+ *  phandle1: node1 {
+ *  	#list-cells = <2>;
+ *  };
+ *
+ *  phandle2: node2 {
+ *  	#list-cells = <1>;
+ *  };
+ *
+ *  phandle3: node3 {
+ *  	#list-cells = <1>;
+ *  	list-map = <0 &phandle2 3>,
+ *  		   <1 &phandle2 2>,
+ *  		   <2 &phandle1 5 1>;
+ *  	list-map-mask = <0x3>;
+ *  };
+ *
+ *  node4 {
+ *  	list = <&phandle1 1 2 &phandle3 0>;
+ *  };
+ *
+ *  To get a device_node of the ``node2`` node you may call this:
+ *  of_parse_phandle_with_args(node4, "list", "list", 1, &args);
  */
 int of_parse_phandle_with_args_map(const struct device_node *np,
 				   const char *list_name,
@@ -1696,18 +1695,18 @@ EXPORT_SYMBOL(of_parse_phandle_with_args_map);
  *
  * Example:
  *
- * phandle1: node1 {
- * }
+ *  phandle1: node1 {
+ *  };
  *
- * phandle2: node2 {
- * }
+ *  phandle2: node2 {
+ *  };
  *
- * node3 {
- *	list = <&phandle1 0 2 &phandle2 2 3>;
- * }
+ *  node3 {
+ *  	list = <&phandle1 0 2 &phandle2 2 3>;
+ *  };
  *
- * To get a device_node of the `node2' node you may call this:
- * of_parse_phandle_with_fixed_args(node3, "list", 2, 1, &args);
+ *  To get a device_node of the ``node2`` node you may call this:
+ *  of_parse_phandle_with_fixed_args(node3, "list", 2, 1, &args);
  */
 int of_parse_phandle_with_fixed_args(const struct device_node *np,
 				const char *list_name, int cell_count,
@@ -1952,13 +1951,12 @@ static void of_alias_add(struct alias_prop *ap, struct device_node *np,
 
 /**
  * of_alias_scan - Scan all properties of the 'aliases' node
+ * @dt_alloc:	An allocator that provides a virtual address to memory
+ *		for storing the resulting tree
  *
  * The function scans all the properties of the 'aliases' node and populates
  * the global lookup table with the properties.  It returns the
  * number of alias properties found, or an error code in case of failure.
- *
- * @dt_alloc:	An allocator that provides a virtual address to memory
- *		for storing the resulting tree
  */
 void of_alias_scan(void * (*dt_alloc)(u64 size, u64 align))
 {
@@ -2153,12 +2151,12 @@ bool of_console_check(struct device_node *dn, char *name, int index)
 EXPORT_SYMBOL_GPL(of_console_check);
 
 /**
- *	of_find_next_cache_node - Find a node's subsidiary cache
- *	@np:	node of type "cpu" or "cache"
+ * of_find_next_cache_node - Find a node's subsidiary cache
+ * @np:	node of type "cpu" or "cache"
  *
- *	Returns a node pointer with refcount incremented, use
- *	of_node_put() on it when done.  Caller should hold a reference
- *	to np.
+ * Return: A node pointer with refcount incremented, use
+ * of_node_put() on it when done.  Caller should hold a reference
+ * to np.
  */
 struct device_node *of_find_next_cache_node(const struct device_node *np)
 {
diff --git a/drivers/of/fdt.c b/drivers/of/fdt.c
index 4d6d195e089a..ba53da9c3895 100644
--- a/drivers/of/fdt.c
+++ b/drivers/of/fdt.c
@@ -349,11 +349,6 @@ static int unflatten_dt_nodes(const void *blob,
 
 /**
  * __unflatten_device_tree - create tree of device_nodes from flat blob
- *
- * unflattens a device-tree, creating the
- * tree of struct device_node. It also fills the "name" and "type"
- * pointers of the nodes so the normal device-tree walking functions
- * can be used.
  * @blob: The blob to expand
  * @dad: Parent device node
  * @mynodes: The device_node tree created by the call
@@ -361,6 +356,10 @@ static int unflatten_dt_nodes(const void *blob,
  * for the resulting tree
  * @detached: if true set OF_DETACHED on @mynodes
  *
+ * unflattens a device-tree, creating the tree of struct device_node. It also
+ * fills the "name" and "type" pointers of the nodes so the normal device-tree
+ * walking functions can be used.
+ *
  * Returns NULL on failure or the memory chunk containing the unflattened
  * device tree on success.
  */
-- 
2.27.0

Re: [PATCH 6/8] of: Fix kerneldoc output formatting

[Mauro Carvalho Chehab]

Em Thu, 25 Mar 2021 10:47:11 -0600
Rob Herring <robh@kernel.org> escreveu:

> The indentation of the kerneldoc comments affects the output formatting.
> Leading tabs in particular don't work, and sections need to be indented
> under the section header.
> 
> The example snippets for DT source in the comments still have some
> formatting issues, but there doesn't seem to be any way to do multi-line
> literal blocks in kerneldoc.
> 
> Cc: Frank Rowand <frowand.list@gmail.com>
> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
> Signed-off-by: Rob Herring <robh@kernel.org>
> ---
> 
> Note the dts examples still cause warnings. I couldn't find any way to 
> do a literal block and fix them. Minimally, there needs to be a way to 
> escape ':' and not create sections:
> 
> Documentation/devicetree/kernel-api:11: ../drivers/of/base.c:1466: WARNING: Definition list ends without a blank line; unexpected unindent.

You can do something like this:

/**
 * of_parse_phandle_with_args() - Find a node pointed by phandle in a list
 * @np:		pointer to a device tree node containing a list
 * @list_name:	property name that contains a list
 * @cells_name:	property name that specifies phandles' arguments count
 * @index:	index of a phandle to parse out
 * @out_args:	optional pointer to output arguments structure (will be filled)
 *
 * This function is useful to parse lists of phandles and their arguments.
 * Returns 0 on success and fills out_args, on error returns appropriate
 * errno value.
 *
 * Caller is responsible to call of_node_put() on the returned out_args->np
 * pointer.
 *
 * For example::
 *
 *	phandle1: node1 {
 *		#list-cells = <2>;
 *	};
 *
 *	phandle2: node2 {
 *		#list-cells = <1>;
 *	};
 *
 *	node3 {
 *		list = <&phandle1 1 2 &phandle2 3>;
 *	};
 *
 * To get a device_node of the ``node2`` node you may call this:
 * of_parse_phandle_with_args(node3, "list", "#list-cells", 1, &args);
 */


The problem is that using just:

/**
 ...
 * Example::
 ...

Would make confusion with an existing regex at kernel-doc script that
parses a regex similar to this:

	\*\s+(\w+):

Into:
	**$1**

So, using two words fix the issue.

Granted, this is something that could be improved at kernel-doc with
something like (untested):

<snip>
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index cb92d0e1e932..cea82e004fce 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -392,7 +392,7 @@ my $doc_com_body = '\s*\* ?';
 my $doc_decl = $doc_com . '(\w+)';
 # @params and a strictly limited set of supported section names
 my $doc_sect = $doc_com .
-    '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
+    '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:]*)$';
 my $doc_content = $doc_com_body . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
 my $doc_inline_start = '^\s*/\*\*\s*$';
</snip>

I'll run some tests if the above works and submit a separate patch
addressing it, likely tomorrow.

Thanks,
Mauro

[PATCH] kernel-doc: better handle '::' sequences

[Mauro Carvalho Chehab]

Right now, if one of the following headers end with a '::', the
kernel-doc script will do the wrong thing:

	description|context|returns?|notes?|examples?

The real issue is with examples, as people could try to write
something like:

	example::

		/* Some C code */

and this won't be properly evaluated. So, improve the regex
to not catch '\w+::' regex for the above identifiers.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index cb92d0e1e932..0ecd71477a16 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -392,7 +392,7 @@ my $doc_com_body = '\s*\* ?';
 my $doc_decl = $doc_com . '(\w+)';
 # @params and a strictly limited set of supported section names
 my $doc_sect = $doc_com .
-    '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
+    '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:]*)$';
 my $doc_content = $doc_com_body . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
 my $doc_inline_start = '^\s*/\*\*\s*$';
-- 
2.30.2

Re: [PATCH] kernel-doc: better handle '::' sequences

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> Right now, if one of the following headers end with a '::', the
> kernel-doc script will do the wrong thing:
>
> 	description|context|returns?|notes?|examples?
>
> The real issue is with examples, as people could try to write
> something like:
>
> 	example::
>
> 		/* Some C code */
>
> and this won't be properly evaluated. So, improve the regex
> to not catch '\w+::' regex for the above identifiers.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  scripts/kernel-doc | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Ah....wouldn't it be nice if kerneldoc comments had just been RST from
the beginning?  I don't think we're fixing that at this point, though,
so this makes sense; applied.

Thanks,

jon

Re: [PATCH] kernel-doc: better handle '::' sequences

[Matthew Wilcox]

On Thu, Mar 25, 2021 at 12:51:25PM -0600, Jonathan Corbet wrote:
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > Right now, if one of the following headers end with a '::', the
> > kernel-doc script will do the wrong thing:
> >
> > 	description|context|returns?|notes?|examples?
> >
> > The real issue is with examples, as people could try to write
> > something like:
> >
> > 	example::
> >
> > 		/* Some C code */
> >
> > and this won't be properly evaluated. So, improve the regex
> > to not catch '\w+::' regex for the above identifiers.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  scripts/kernel-doc | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> Ah....wouldn't it be nice if kerneldoc comments had just been RST from
> the beginning?  I don't think we're fixing that at this point, though,
> so this makes sense; applied.

Well ...

If somebody wants to write a new tool (*) that extracts documentation
written in a different format, I think that could be done.  Because the
hard part of writing documentation is getting the person who knows the
code to get everything that's in their brain into words, not really
the formatting.

If somebody did want to write such a tool, I think we'd also want a
tool that turns the existing kernel-doc into the new format, because
maintaining two function-doc formats would be awful.

https://blog.golang.org/godoc would be my preferred format ... the less
information repeated from the actual function, the better.  But if
we're actually going to have rust in the kernel, perhaps rustdoc is
better.  https://doc.rust-lang.org/beta/rust-by-example/meta/doc.html

(*) because nobody actually likes kernel-doc.pl, right?

Re: [PATCH] kernel-doc: better handle '::' sequences

[Jonathan Corbet]

Matthew Wilcox <willy@infradead.org> writes:

> On Thu, Mar 25, 2021 at 12:51:25PM -0600, Jonathan Corbet wrote:
>> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
>> 
>> > Right now, if one of the following headers end with a '::', the
>> > kernel-doc script will do the wrong thing:
>> >
>> > 	description|context|returns?|notes?|examples?
>> >
>> > The real issue is with examples, as people could try to write
>> > something like:
>> >
>> > 	example::
>> >
>> > 		/* Some C code */
>> >
>> > and this won't be properly evaluated. So, improve the regex
>> > to not catch '\w+::' regex for the above identifiers.
>> >
>> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>> > ---
>> >  scripts/kernel-doc | 2 +-
>> >  1 file changed, 1 insertion(+), 1 deletion(-)
>> 
>> Ah....wouldn't it be nice if kerneldoc comments had just been RST from
>> the beginning?  I don't think we're fixing that at this point, though,
>> so this makes sense; applied.
>
> Well ...
>
> If somebody wants to write a new tool (*) that extracts documentation
> written in a different format, I think that could be done.  Because the
> hard part of writing documentation is getting the person who knows the
> code to get everything that's in their brain into words, not really
> the formatting.
>
> If somebody did want to write such a tool, I think we'd also want a
> tool that turns the existing kernel-doc into the new format, because
> maintaining two function-doc formats would be awful.

Yeah, the thing is that, as long as we're documenting code with
something other than RST, we *do* have two formats, and they interact
with each other in surprising and unwelcome ways.

I don't really see a fix, though.  Even if we come up with the Perfect
New Format™, I don't want to be the one trying to push through the
patches changing tens of thousands of kerneldoc comments over...

jon

Re: [PATCH] kernel-doc: better handle '::' sequences

[Matthew Wilcox]

On Thu, Mar 25, 2021 at 03:04:00PM -0600, Jonathan Corbet wrote:
> Matthew Wilcox <willy@infradead.org> writes:
> > Well ...
> >
> > If somebody wants to write a new tool (*) that extracts documentation
> > written in a different format, I think that could be done.  Because the
> > hard part of writing documentation is getting the person who knows the
> > code to get everything that's in their brain into words, not really
> > the formatting.
> >
> > If somebody did want to write such a tool, I think we'd also want a
> > tool that turns the existing kernel-doc into the new format, because
> > maintaining two function-doc formats would be awful.
> 
> Yeah, the thing is that, as long as we're documenting code with
> something other than RST, we *do* have two formats, and they interact
> with each other in surprising and unwelcome ways.
> 
> I don't really see a fix, though.  Even if we come up with the Perfect
> New Format™, I don't want to be the one trying to push through the
> patches changing tens of thousands of kerneldoc comments over...

I can't argue with either of your points.

The rust code is alredy coming though ...

rust/kernel/buffer.rs:/// A pre-allocated buffer that implements [`core::fmt::Write`].

so now we have three formats.  Markdown and RST are _very_ similar, but
not identical [1].  Oh, and even better we now have three distinct tools --
kerneldoc, rustdoc and sphinx.  Have the rust people reached out to you
about integrating the various docs?

[1] https://en.wikipedia.org/wiki/Lightweight_markup_language#Comparison_of_lightweight_markup_language_syntax

Re: [PATCH] kernel-doc: better handle '::' sequences

[Jonathan Corbet]

Matthew Wilcox <willy@infradead.org> writes:

> The rust code is alredy coming though ...
>
> rust/kernel/buffer.rs:/// A pre-allocated buffer that implements [`core::fmt::Write`].
>
> so now we have three formats.  Markdown and RST are _very_ similar, but
> not identical [1].  Oh, and even better we now have three distinct tools --
> kerneldoc, rustdoc and sphinx.  Have the rust people reached out to you
> about integrating the various docs?

I have talked with them a bit, yes, but without any clear conclusions at
this point.  The Rust world has its own way of doing things with regard
to documentation, and I don't want to tell them they can't use it in the
kernel context.  So I think there's going to be a certain amount of
groping around for the best solution.

We did come to the mutual agreement that teaching kernel-doc to parse
Rust code as well was not an ideal solution.  Probably there will be
some sort of tool to translate between rustdoc and our sphinx setup.
Beyond that, we'll see how it goes.

jon

Re: [PATCH] kernel-doc: better handle '::' sequences

[Matthew Wilcox]

On Thu, Mar 25, 2021 at 04:30:32PM -0600, Jonathan Corbet wrote:
> Matthew Wilcox <willy@infradead.org> writes:
> 
> > The rust code is alredy coming though ...
> >
> > rust/kernel/buffer.rs:/// A pre-allocated buffer that implements [`core::fmt::Write`].
> >
> > so now we have three formats.  Markdown and RST are _very_ similar, but
> > not identical [1].  Oh, and even better we now have three distinct tools --
> > kerneldoc, rustdoc and sphinx.  Have the rust people reached out to you
> > about integrating the various docs?
> 
> I have talked with them a bit, yes, but without any clear conclusions at
> this point.  The Rust world has its own way of doing things with regard
> to documentation, and I don't want to tell them they can't use it in the
> kernel context.  So I think there's going to be a certain amount of
> groping around for the best solution.
> 
> We did come to the mutual agreement that teaching kernel-doc to parse
> Rust code as well was not an ideal solution.  Probably there will be
> some sort of tool to translate between rustdoc and our sphinx setup.
> Beyond that, we'll see how it goes.

In the spirit of groping around for the best solution, I did some looking
around at various options, including using rustdoc for .c files (that
uses Markdown, which appears to be strictly worse than rST for our
purposes).

So here's my "modest proposal":

 - Similar to our ".. kernel-doc::" invocation in .rst files, handle
   ".. rustdoc::" (insert weeks of hacking here)
 - Now add ".. rst-doc::" which parses .c files like [1] kernel-doc
   does, but interprets a different style of comment and actually does
   most of the repetitive boring bits for you.

For example, xa_load:

/**
 * xa_load() - Load an entry from an XArray.
 * @xa: XArray.
 * @index: index into array.
 *
 * Context: Any context.  Takes and releases the RCU lock.
 * Return: The entry at @index in @xa.
 */
void *xa_load(struct xarray *xa, unsigned long index)

//rST
// Load an entry from an XArray.
//
// :Context: Any context.  Takes and releases the RCU lock.
// :Return: The entry in `xa` at `index`.
void *xa_load(struct xarray *xa, unsigned long index)

(more complex example below [2])

Things I considered:

 - Explicitly document that this is rST markup instead of Markdown or
   whatever.
 - Don't repeat the name of the function.  The tool can figure it out.
 - Don't force documenting each parameter.  Often they are obvious
   and there's really nothing interesting to say about the parameter.
   Witness the number of '@foo: The foo' (of type struct foo) that we
   have scattered throughout the tree.  It's not that the documenter is
   lazy, it's that there's genuinely nothing to say here.
 - Use `interpreted text` to refer to parameters instead of *emphasis* or
   **strong emphasis**.  The tool can turn that into whatever markup
   is appropriate.
 - Use field lists for Context and Return instead of sections.  The markup
   is simpler to use, and I think the rendered output is better.

[1] by which i mean "in a completely different way from, but similar in
    concept"

[2] More complex example:

/**
 * xa_store() - Store this entry in the XArray.
 * @xa: XArray.
 * @index: Index into array.
 * @entry: New entry.
 * @gfp: Memory allocation flags.
 *
 * After this function returns, loads from this index will return @entry.
 * Storing into an existing multi-index entry updates the entry of every index.
 * The marks associated with @index are unaffected unless @entry is %NULL.
 *
 * Context: Any context.  Takes and releases the xa_lock.
 * May sleep if the @gfp flags permit.
 * Return: The old entry at this index on success, xa_err(-EINVAL) if @entry
 * cannot be stored in an XArray, or xa_err(-ENOMEM) if memory allocation
 * failed.
 */
void *xa_store(struct xarray *xa, unsigned long index, void *entry, gfp_t gfp)

//rST
// Store an entry in the XArray.
//
// After this function returns, loads from `index` will return `entry`.
// Storing into an existing multi-index entry updates the entry of every index.
// The marks associated with `index` are unaffected unless `entry` is ``NULL``.
//
// :Context: Any context.  Takes and releases the xa_lock.
//    May sleep if the `gfp` flags permit.
// :Return: The old entry at this index on success, xa_err(-EINVAL) if `entry`
//    cannot be stored in an XArray, or xa_err(-ENOMEM) if memory allocation
//    failed.
void *xa_store(struct xarray *xa, unsigned long index, void *entry, gfp_t gfp)

Re: [PATCH] kernel-doc: better handle '::' sequences

[Jani Nikula]

On Mon, 29 Mar 2021, Matthew Wilcox <willy@infradead.org> wrote:
> On Thu, Mar 25, 2021 at 04:30:32PM -0600, Jonathan Corbet wrote:
>> Matthew Wilcox <willy@infradead.org> writes:
>> 
>> > The rust code is alredy coming though ...
>> >
>> > rust/kernel/buffer.rs:/// A pre-allocated buffer that implements [`core::fmt::Write`].
>> >
>> > so now we have three formats.  Markdown and RST are _very_ similar, but
>> > not identical [1].  Oh, and even better we now have three distinct tools --
>> > kerneldoc, rustdoc and sphinx.  Have the rust people reached out to you
>> > about integrating the various docs?
>> 
>> I have talked with them a bit, yes, but without any clear conclusions at
>> this point.  The Rust world has its own way of doing things with regard
>> to documentation, and I don't want to tell them they can't use it in the
>> kernel context.  So I think there's going to be a certain amount of
>> groping around for the best solution.
>> 
>> We did come to the mutual agreement that teaching kernel-doc to parse
>> Rust code as well was not an ideal solution.  Probably there will be
>> some sort of tool to translate between rustdoc and our sphinx setup.
>> Beyond that, we'll see how it goes.
>
> In the spirit of groping around for the best solution, I did some looking
> around at various options, including using rustdoc for .c files (that
> uses Markdown, which appears to be strictly worse than rST for our
> purposes).
>
> So here's my "modest proposal":
>
>  - Similar to our ".. kernel-doc::" invocation in .rst files, handle
>    ".. rustdoc::" (insert weeks of hacking here)
>  - Now add ".. rst-doc::" which parses .c files like [1] kernel-doc
>    does, but interprets a different style of comment and actually does
>    most of the repetitive boring bits for you.

As a hobby, I've written a Sphinx extension to use Clang to parse the
code and extract pure reStructuredText documentation comments with
minimal conversions [1]. No additional syntax. Just use reStructuredText
for everything instead of inventing your own.

I'm not proposing to use that in kernel, at all. It was more like a
diversion from the kernel documentation.

But based on my experience with the old and new kernel documentation
systems and the hobby one, the one takeaway is to not create new
syntaxes, grammars, parsers, or preprocessors to be maintained by the
kernel community. Just don't. Take what's working and supported by other
projects, and add the minimal glue using Sphinx extensions to put it
together, and no more.

Of course, we couldn't ditch kernel-doc the script, but we managed to
trim it down quite a bit. OTOH, there have been a number of additions
outside of Sphinx in Makefiles and custom tools in various languages
that I'm really not happy about. It's all too reminiscient of the old
DocBook toolchain, while Sphinx was supposed to be the one tool to tie
it all together, partially chosen because of the extension support.


BR,
Jani.


[1] https://github.com/jnikula/hawkmoth


>
> For example, xa_load:
>
> /**
>  * xa_load() - Load an entry from an XArray.
>  * @xa: XArray.
>  * @index: index into array.
>  *
>  * Context: Any context.  Takes and releases the RCU lock.
>  * Return: The entry at @index in @xa.
>  */
> void *xa_load(struct xarray *xa, unsigned long index)
>
> //rST
> // Load an entry from an XArray.
> //
> // :Context: Any context.  Takes and releases the RCU lock.
> // :Return: The entry in `xa` at `index`.
> void *xa_load(struct xarray *xa, unsigned long index)
>
> (more complex example below [2])
>
> Things I considered:
>
>  - Explicitly document that this is rST markup instead of Markdown or
>    whatever.
>  - Don't repeat the name of the function.  The tool can figure it out.
>  - Don't force documenting each parameter.  Often they are obvious
>    and there's really nothing interesting to say about the parameter.
>    Witness the number of '@foo: The foo' (of type struct foo) that we
>    have scattered throughout the tree.  It's not that the documenter is
>    lazy, it's that there's genuinely nothing to say here.
>  - Use `interpreted text` to refer to parameters instead of *emphasis* or
>    **strong emphasis**.  The tool can turn that into whatever markup
>    is appropriate.
>  - Use field lists for Context and Return instead of sections.  The markup
>    is simpler to use, and I think the rendered output is better.
>
> [1] by which i mean "in a completely different way from, but similar in
>     concept"
>
> [2] More complex example:
>
> /**
>  * xa_store() - Store this entry in the XArray.
>  * @xa: XArray.
>  * @index: Index into array.
>  * @entry: New entry.
>  * @gfp: Memory allocation flags.
>  *
>  * After this function returns, loads from this index will return @entry.
>  * Storing into an existing multi-index entry updates the entry of every index.
>  * The marks associated with @index are unaffected unless @entry is %NULL.
>  *
>  * Context: Any context.  Takes and releases the xa_lock.
>  * May sleep if the @gfp flags permit.
>  * Return: The old entry at this index on success, xa_err(-EINVAL) if @entry
>  * cannot be stored in an XArray, or xa_err(-ENOMEM) if memory allocation
>  * failed.
>  */
> void *xa_store(struct xarray *xa, unsigned long index, void *entry, gfp_t gfp)
>
> //rST
> // Store an entry in the XArray.
> //
> // After this function returns, loads from `index` will return `entry`.
> // Storing into an existing multi-index entry updates the entry of every index.
> // The marks associated with `index` are unaffected unless `entry` is ``NULL``.
> //
> // :Context: Any context.  Takes and releases the xa_lock.
> //    May sleep if the `gfp` flags permit.
> // :Return: The old entry at this index on success, xa_err(-EINVAL) if `entry`
> //    cannot be stored in an XArray, or xa_err(-ENOMEM) if memory allocation
> //    failed.
> void *xa_store(struct xarray *xa, unsigned long index, void *entry, gfp_t gfp)
>

-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [PATCH] kernel-doc: better handle '::' sequences

[Matthew Wilcox]

On Mon, Mar 29, 2021 at 09:33:30PM +0300, Jani Nikula wrote:
> On Mon, 29 Mar 2021, Matthew Wilcox <willy@infradead.org> wrote:
> > So here's my "modest proposal":
> >
> >  - Similar to our ".. kernel-doc::" invocation in .rst files, handle
> >    ".. rustdoc::" (insert weeks of hacking here)
> >  - Now add ".. rst-doc::" which parses .c files like [1] kernel-doc
> >    does, but interprets a different style of comment and actually does
> >    most of the repetitive boring bits for you.
> 
> As a hobby, I've written a Sphinx extension to use Clang to parse the
> code and extract pure reStructuredText documentation comments with
> minimal conversions [1]. No additional syntax. Just use reStructuredText
> for everything instead of inventing your own.
> 
> I'm not proposing to use that in kernel, at all. It was more like a
> diversion from the kernel documentation.

Actually, that looks like my proposal, except that it uses the same /**
as kernel-doc, so you can't tell whether a comment is intended to be
interpreted by kernel-doc or hawkmoth.

https://github.com/jnikula/hawkmoth/blob/master/test/example-70-function.c

If the introduction were "/*rST" instead of "/**", would we have
consensus?  It gives us a path to let people intermix kernel-doc and
hawkmoth comments in the same file, which would be amazing.

> But based on my experience with the old and new kernel documentation
> systems and the hobby one, the one takeaway is to not create new
> syntaxes, grammars, parsers, or preprocessors to be maintained by the
> kernel community. Just don't. Take what's working and supported by other
> projects, and add the minimal glue using Sphinx extensions to put it
> together, and no more.
> 
> Of course, we couldn't ditch kernel-doc the script, but we managed to
> trim it down quite a bit. OTOH, there have been a number of additions
> outside of Sphinx in Makefiles and custom tools in various languages
> that I'm really not happy about. It's all too reminiscient of the old
> DocBook toolchain, while Sphinx was supposed to be the one tool to tie
> it all together, partially chosen because of the extension support.
> 
> 
> BR,
> Jani.
> 
> 
> [1] https://github.com/jnikula/hawkmoth
> 
> 
> >
> > For example, xa_load:
> >
> > /**
> >  * xa_load() - Load an entry from an XArray.
> >  * @xa: XArray.
> >  * @index: index into array.
> >  *
> >  * Context: Any context.  Takes and releases the RCU lock.
> >  * Return: The entry at @index in @xa.
> >  */
> > void *xa_load(struct xarray *xa, unsigned long index)
> >
> > //rST
> > // Load an entry from an XArray.
> > //
> > // :Context: Any context.  Takes and releases the RCU lock.
> > // :Return: The entry in `xa` at `index`.
> > void *xa_load(struct xarray *xa, unsigned long index)
> >
> > (more complex example below [2])
> >
> > Things I considered:
> >
> >  - Explicitly document that this is rST markup instead of Markdown or
> >    whatever.
> >  - Don't repeat the name of the function.  The tool can figure it out.
> >  - Don't force documenting each parameter.  Often they are obvious
> >    and there's really nothing interesting to say about the parameter.
> >    Witness the number of '@foo: The foo' (of type struct foo) that we
> >    have scattered throughout the tree.  It's not that the documenter is
> >    lazy, it's that there's genuinely nothing to say here.
> >  - Use `interpreted text` to refer to parameters instead of *emphasis* or
> >    **strong emphasis**.  The tool can turn that into whatever markup
> >    is appropriate.
> >  - Use field lists for Context and Return instead of sections.  The markup
> >    is simpler to use, and I think the rendered output is better.
> >
> > [1] by which i mean "in a completely different way from, but similar in
> >     concept"
> >
> > [2] More complex example:
> >
> > /**
> >  * xa_store() - Store this entry in the XArray.
> >  * @xa: XArray.
> >  * @index: Index into array.
> >  * @entry: New entry.
> >  * @gfp: Memory allocation flags.
> >  *
> >  * After this function returns, loads from this index will return @entry.
> >  * Storing into an existing multi-index entry updates the entry of every index.
> >  * The marks associated with @index are unaffected unless @entry is %NULL.
> >  *
> >  * Context: Any context.  Takes and releases the xa_lock.
> >  * May sleep if the @gfp flags permit.
> >  * Return: The old entry at this index on success, xa_err(-EINVAL) if @entry
> >  * cannot be stored in an XArray, or xa_err(-ENOMEM) if memory allocation
> >  * failed.
> >  */
> > void *xa_store(struct xarray *xa, unsigned long index, void *entry, gfp_t gfp)
> >
> > //rST
> > // Store an entry in the XArray.
> > //
> > // After this function returns, loads from `index` will return `entry`.
> > // Storing into an existing multi-index entry updates the entry of every index.
> > // The marks associated with `index` are unaffected unless `entry` is ``NULL``.
> > //
> > // :Context: Any context.  Takes and releases the xa_lock.
> > //    May sleep if the `gfp` flags permit.
> > // :Return: The old entry at this index on success, xa_err(-EINVAL) if `entry`
> > //    cannot be stored in an XArray, or xa_err(-ENOMEM) if memory allocation
> > //    failed.
> > void *xa_store(struct xarray *xa, unsigned long index, void *entry, gfp_t gfp)
> >
> 
> -- 
> Jani Nikula, Intel Open Source Graphics Center

Re: [PATCH] kernel-doc: better handle '::' sequences

[Jani Nikula]

On Mon, 29 Mar 2021, Matthew Wilcox <willy@infradead.org> wrote:
> On Mon, Mar 29, 2021 at 09:33:30PM +0300, Jani Nikula wrote:
>> On Mon, 29 Mar 2021, Matthew Wilcox <willy@infradead.org> wrote:
>> > So here's my "modest proposal":
>> >
>> >  - Similar to our ".. kernel-doc::" invocation in .rst files, handle
>> >    ".. rustdoc::" (insert weeks of hacking here)
>> >  - Now add ".. rst-doc::" which parses .c files like [1] kernel-doc
>> >    does, but interprets a different style of comment and actually does
>> >    most of the repetitive boring bits for you.
>> 
>> As a hobby, I've written a Sphinx extension to use Clang to parse the
>> code and extract pure reStructuredText documentation comments with
>> minimal conversions [1]. No additional syntax. Just use reStructuredText
>> for everything instead of inventing your own.
>> 
>> I'm not proposing to use that in kernel, at all. It was more like a
>> diversion from the kernel documentation.
>
> Actually, that looks like my proposal, except that it uses the same /**
> as kernel-doc, so you can't tell whether a comment is intended to be
> interpreted by kernel-doc or hawkmoth.
>
> https://github.com/jnikula/hawkmoth/blob/master/test/example-70-function.c
>
> If the introduction were "/*rST" instead of "/**", would we have
> consensus?  It gives us a path to let people intermix kernel-doc and
> hawkmoth comments in the same file, which would be amazing.

If you want to allow two syntaxes for documentation comments (current
kernel-doc and pure reStructuredText with just the comment markers and
indentation removed) I think the natural first step would be to modify
kernel-doc the perl script to support that. It would probably even be
trivial.

Hawkmoth uses Clang for parsing, with none of the kernel specific stuff
that kernel-doc has, such as EXPORT_SYMBOL(). It makes sense for a pet
project with a clean break. I don't know if anyone has the bandwidth or
desire to re-implement the kernel specific stuff on top of Clang. (I
know I don't, I started the project because I wanted that clean break to
begin with!)

The real question is, is it a good idea to support multiple formats at
all? (N.b. I'm not a fan of extending the kernel-doc syntax either.)

BR,
Jani.


>
>> But based on my experience with the old and new kernel documentation
>> systems and the hobby one, the one takeaway is to not create new
>> syntaxes, grammars, parsers, or preprocessors to be maintained by the
>> kernel community. Just don't. Take what's working and supported by other
>> projects, and add the minimal glue using Sphinx extensions to put it
>> together, and no more.
>> 
>> Of course, we couldn't ditch kernel-doc the script, but we managed to
>> trim it down quite a bit. OTOH, there have been a number of additions
>> outside of Sphinx in Makefiles and custom tools in various languages
>> that I'm really not happy about. It's all too reminiscient of the old
>> DocBook toolchain, while Sphinx was supposed to be the one tool to tie
>> it all together, partially chosen because of the extension support.
>> 
>> 
>> BR,
>> Jani.
>> 
>> 
>> [1] https://github.com/jnikula/hawkmoth
>> 
>> 
>> >
>> > For example, xa_load:
>> >
>> > /**
>> >  * xa_load() - Load an entry from an XArray.
>> >  * @xa: XArray.
>> >  * @index: index into array.
>> >  *
>> >  * Context: Any context.  Takes and releases the RCU lock.
>> >  * Return: The entry at @index in @xa.
>> >  */
>> > void *xa_load(struct xarray *xa, unsigned long index)
>> >
>> > //rST
>> > // Load an entry from an XArray.
>> > //
>> > // :Context: Any context.  Takes and releases the RCU lock.
>> > // :Return: The entry in `xa` at `index`.
>> > void *xa_load(struct xarray *xa, unsigned long index)
>> >
>> > (more complex example below [2])
>> >
>> > Things I considered:
>> >
>> >  - Explicitly document that this is rST markup instead of Markdown or
>> >    whatever.
>> >  - Don't repeat the name of the function.  The tool can figure it out.
>> >  - Don't force documenting each parameter.  Often they are obvious
>> >    and there's really nothing interesting to say about the parameter.
>> >    Witness the number of '@foo: The foo' (of type struct foo) that we
>> >    have scattered throughout the tree.  It's not that the documenter is
>> >    lazy, it's that there's genuinely nothing to say here.
>> >  - Use `interpreted text` to refer to parameters instead of *emphasis* or
>> >    **strong emphasis**.  The tool can turn that into whatever markup
>> >    is appropriate.
>> >  - Use field lists for Context and Return instead of sections.  The markup
>> >    is simpler to use, and I think the rendered output is better.
>> >
>> > [1] by which i mean "in a completely different way from, but similar in
>> >     concept"
>> >
>> > [2] More complex example:
>> >
>> > /**
>> >  * xa_store() - Store this entry in the XArray.
>> >  * @xa: XArray.
>> >  * @index: Index into array.
>> >  * @entry: New entry.
>> >  * @gfp: Memory allocation flags.
>> >  *
>> >  * After this function returns, loads from this index will return @entry.
>> >  * Storing into an existing multi-index entry updates the entry of every index.
>> >  * The marks associated with @index are unaffected unless @entry is %NULL.
>> >  *
>> >  * Context: Any context.  Takes and releases the xa_lock.
>> >  * May sleep if the @gfp flags permit.
>> >  * Return: The old entry at this index on success, xa_err(-EINVAL) if @entry
>> >  * cannot be stored in an XArray, or xa_err(-ENOMEM) if memory allocation
>> >  * failed.
>> >  */
>> > void *xa_store(struct xarray *xa, unsigned long index, void *entry, gfp_t gfp)
>> >
>> > //rST
>> > // Store an entry in the XArray.
>> > //
>> > // After this function returns, loads from `index` will return `entry`.
>> > // Storing into an existing multi-index entry updates the entry of every index.
>> > // The marks associated with `index` are unaffected unless `entry` is ``NULL``.
>> > //
>> > // :Context: Any context.  Takes and releases the xa_lock.
>> > //    May sleep if the `gfp` flags permit.
>> > // :Return: The old entry at this index on success, xa_err(-EINVAL) if `entry`
>> > //    cannot be stored in an XArray, or xa_err(-ENOMEM) if memory allocation
>> > //    failed.
>> > void *xa_store(struct xarray *xa, unsigned long index, void *entry, gfp_t gfp)
>> >
>> 
>> -- 
>> Jani Nikula, Intel Open Source Graphics Center

-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [PATCH] kernel-doc: better handle '::' sequences

[Markus Heiser]

Am 30.03.21 um 13:35 schrieb Jani Nikula:
>> If the introduction were "/*rST" instead of "/**", would we have
>> consensus?  It gives us a path to let people intermix kernel-doc and
>> hawkmoth comments in the same file, which would be amazing.

> If you want to allow two syntaxes for documentation comments (current
> kernel-doc and pure reStructuredText with just the comment markers and
> indentation removed) I think the natural first step would be to modify
> kernel-doc the perl script to support that. It would probably even be
> trivial.

My 2cent: to tag the markup of the documentation, in python they
use a variable named __docformat__ [PEP-258] / e.g.:

         __docformat__ = "restructuredtext en"

[PEP-258] https://www.python.org/dev/peps/pep-0258/#choice-of-docstring-format

 > Perhaps the bare minimum is running rustdoc first, and generating the
 > results into Sphinx static pages [1], to make them part of the
 > whole. Even if the HTML style might be different.

Cross referencing will be problematic, I think.

   -- Markus --

Re: [PATCH] kernel-doc: better handle '::' sequences

[Matthew Wilcox]

On Tue, Mar 30, 2021 at 02:43:45PM +0200, Markus Heiser wrote:
> 
> Am 30.03.21 um 13:35 schrieb Jani Nikula:
> > > If the introduction were "/*rST" instead of "/**", would we have
> > > consensus?  It gives us a path to let people intermix kernel-doc and
> > > hawkmoth comments in the same file, which would be amazing.
> 
> > If you want to allow two syntaxes for documentation comments (current
> > kernel-doc and pure reStructuredText with just the comment markers and
> > indentation removed) I think the natural first step would be to modify
> > kernel-doc the perl script to support that. It would probably even be
> > trivial.
> 
> My 2cent: to tag the markup of the documentation, in python they
> use a variable named __docformat__ [PEP-258] / e.g.:
> 
>         __docformat__ = "restructuredtext en"
> 
> [PEP-258] https://www.python.org/dev/peps/pep-0258/#choice-of-docstring-format

I don't think we need to do that.  We can use

.. kernel-doc:: foo.c 

to indicate the comments are in kernel-doc format and

.. hawkmoth:: bar.c

to indicate the comments are in hawkmoth format.  Of course, that means
we have to choose for an entire .c file whether it's in hawkmoth or
kernel-doc format, but that's also true for pep-258.

> > Perhaps the bare minimum is running rustdoc first, and generating the
> > results into Sphinx static pages [1], to make them part of the
> > whole. Even if the HTML style might be different.
> 
> Cross referencing will be problematic, I think.

That would be a second step.  I'd rather see the rst files gain the
ability to have:

.. rustdoc:: quux.rs

to bring the markdown into the sphinx system.

Re: kerneldoc and rust (was [PATCH] kernel-doc: better handle '::' sequences)

[Jonathan Corbet]

Matthew Wilcox <willy@infradead.org> writes:

If we're going to talk about incorporating Rust into the doc system, we
should probably include some Rust folks - thus, I'm adding Miguel.

> On Thu, Mar 25, 2021 at 04:30:32PM -0600, Jonathan Corbet wrote:
>> Matthew Wilcox <willy@infradead.org> writes:
>> 
>> We did come to the mutual agreement that teaching kernel-doc to parse
>> Rust code as well was not an ideal solution.  Probably there will be
>> some sort of tool to translate between rustdoc and our sphinx setup.
>> Beyond that, we'll see how it goes.
>
> In the spirit of groping around for the best solution, I did some looking
> around at various options, including using rustdoc for .c files (that
> uses Markdown, which appears to be strictly worse than rST for our
> purposes).
>
> So here's my "modest proposal":
>
>  - Similar to our ".. kernel-doc::" invocation in .rst files, handle
>    ".. rustdoc::" (insert weeks of hacking here)
>  - Now add ".. rst-doc::" which parses .c files like [1] kernel-doc
>    does, but interprets a different style of comment and actually does
>    most of the repetitive boring bits for you.
>
> For example, xa_load:
>
> /**
>  * xa_load() - Load an entry from an XArray.
>  * @xa: XArray.
>  * @index: index into array.
>  *
>  * Context: Any context.  Takes and releases the RCU lock.
>  * Return: The entry at @index in @xa.
>  */
> void *xa_load(struct xarray *xa, unsigned long index)
>
> //rST
> // Load an entry from an XArray.
> //
> // :Context: Any context.  Takes and releases the RCU lock.
> // :Return: The entry in `xa` at `index`.
> void *xa_load(struct xarray *xa, unsigned long index)
>
> (more complex example below [2])
>
> Things I considered:
>
>  - Explicitly document that this is rST markup instead of Markdown or
>    whatever.
>  - Don't repeat the name of the function.  The tool can figure it out.

That worries me a wee bit just because a common source of problems is
kerneldoc comments becoming separated from the functions they describe
over time.  We finally have tooling to notice that; this seems like a
step in the other direction.

>  - Don't force documenting each parameter.  Often they are obvious
>    and there's really nothing interesting to say about the parameter.
>    Witness the number of '@foo: The foo' (of type struct foo) that we
>    have scattered throughout the tree.  It's not that the documenter is
>    lazy, it's that there's genuinely nothing to say here.

...another failure mode is developers adding parameters and not
documenting them; this would mask that problem too.

>  - Use `interpreted text` to refer to parameters instead of *emphasis* or
>    **strong emphasis**.  The tool can turn that into whatever markup
>    is appropriate.
>  - Use field lists for Context and Return instead of sections.  The markup
>    is simpler to use, and I think the rendered output is better.
>
> [1] by which i mean "in a completely different way from, but similar in
>     concept"
>
> [2] More complex example:
>
> /**
>  * xa_store() - Store this entry in the XArray.
>  * @xa: XArray.
>  * @index: Index into array.
>  * @entry: New entry.
>  * @gfp: Memory allocation flags.
>  *
>  * After this function returns, loads from this index will return @entry.
>  * Storing into an existing multi-index entry updates the entry of every index.
>  * The marks associated with @index are unaffected unless @entry is %NULL.
>  *
>  * Context: Any context.  Takes and releases the xa_lock.
>  * May sleep if the @gfp flags permit.
>  * Return: The old entry at this index on success, xa_err(-EINVAL) if @entry
>  * cannot be stored in an XArray, or xa_err(-ENOMEM) if memory allocation
>  * failed.
>  */
> void *xa_store(struct xarray *xa, unsigned long index, void *entry, gfp_t gfp)
>
> //rST
> // Store an entry in the XArray.
> //
> // After this function returns, loads from `index` will return `entry`.
> // Storing into an existing multi-index entry updates the entry of every index.
> // The marks associated with `index` are unaffected unless `entry` is ``NULL``.
> //
> // :Context: Any context.  Takes and releases the xa_lock.
> //    May sleep if the `gfp` flags permit.
> // :Return: The old entry at this index on success, xa_err(-EINVAL) if `entry`
> //    cannot be stored in an XArray, or xa_err(-ENOMEM) if memory allocation
> //    failed.
> void *xa_store(struct xarray *xa, unsigned long index, void *entry, gfp_t gfp)

Thanks,

jon

Re: kerneldoc and rust (was [PATCH] kernel-doc: better handle '::' sequences)

[Miguel Ojeda]

On Mon, Mar 29, 2021 at 9:34 PM Jonathan Corbet <corbet@lwn.net> wrote:
>
> If we're going to talk about incorporating Rust into the doc system, we
> should probably include some Rust folks - thus, I'm adding Miguel.

Thanks a lot Jonathan for the Cc!

I will read and answer the other emails.

Cheers,
Miguel

Re: [PATCH] kernel-doc: better handle '::' sequences

[Miguel Ojeda]

On Thu, Mar 25, 2021 at 11:18 PM Matthew Wilcox <willy@infradead.org> wrote:
>
> The rust code is alredy coming though ...
>
> rust/kernel/buffer.rs:/// A pre-allocated buffer that implements [`core::fmt::Write`].
>
> so now we have three formats.  Markdown and RST are _very_ similar, but
> not identical [1].  Oh, and even better we now have three distinct tools --
> kerneldoc, rustdoc and sphinx.  Have the rust people reached out to you
> about integrating the various docs?

Yeah, I reached out to Jonathan a few weeks ago to discuss how we will
approach this, because I knew using `rustdoc` and Markdown could be
contentious ;-)

This is the solution we decided to go for the RFC but, of course,
nothing is set in stone:

  1. The "out-of-line" docs in `Documentation/rust/`: these will be in
RST as usual [*]. However, please note this does not include APIs or
anything like that, as it is done in the C side. Only a few "general
documents" that don't fit anywhere else are kept here.

  2. The "inline" docs in Rust source files: these will be parsed by
`rustdoc` and written in Markdown. These will contain the majority of
the Rust documentation. `rustdoc` is designed for Rust code, and
internally uses the Rust compiler, which comes with a number of
advantages.

The generated HTML docs will be showcased in the RFC. It is my hope
that this way we get feedback on them and see if people agree this
approach is worth keeping. We have put an effort (and I have been
annoying contributors enough to that end :-) to provide high-quality
documentation from the get-go.

Please note that we chose this way knowing well that inconsistency and
adding "yet one more tool" needs to come with big advantages to
offset. We think it is the best approach nevertheless!

[*] I discussed with Jonathan using Markdown since Sphinx supports it.
The main advantage would be easier refactoring of comments between the
out- and inline docs. But this is very minor, thus mixing two formats
inside `Documentation/` does not seem like worth it.

Cheers,
Miguel

Re: [PATCH] kernel-doc: better handle '::' sequences

[Jani Nikula]

On Mon, 29 Mar 2021, Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> wrote:
> On Thu, Mar 25, 2021 at 11:18 PM Matthew Wilcox <willy@infradead.org> wrote:
>>
>> The rust code is alredy coming though ...
>>
>> rust/kernel/buffer.rs:/// A pre-allocated buffer that implements [`core::fmt::Write`].
>>
>> so now we have three formats.  Markdown and RST are _very_ similar, but
>> not identical [1].  Oh, and even better we now have three distinct tools --
>> kerneldoc, rustdoc and sphinx.  Have the rust people reached out to you
>> about integrating the various docs?
>
> Yeah, I reached out to Jonathan a few weeks ago to discuss how we will
> approach this, because I knew using `rustdoc` and Markdown could be
> contentious ;-)
>
> This is the solution we decided to go for the RFC but, of course,
> nothing is set in stone:
>
>   1. The "out-of-line" docs in `Documentation/rust/`: these will be in
> RST as usual [*]. However, please note this does not include APIs or
> anything like that, as it is done in the C side. Only a few "general
> documents" that don't fit anywhere else are kept here.
>
>   2. The "inline" docs in Rust source files: these will be parsed by
> `rustdoc` and written in Markdown. These will contain the majority of
> the Rust documentation. `rustdoc` is designed for Rust code, and
> internally uses the Rust compiler, which comes with a number of
> advantages.
>
> The generated HTML docs will be showcased in the RFC. It is my hope
> that this way we get feedback on them and see if people agree this
> approach is worth keeping. We have put an effort (and I have been
> annoying contributors enough to that end :-) to provide high-quality
> documentation from the get-go.
>
> Please note that we chose this way knowing well that inconsistency and
> adding "yet one more tool" needs to come with big advantages to
> offset. We think it is the best approach nevertheless!
>
> [*] I discussed with Jonathan using Markdown since Sphinx supports it.
> The main advantage would be easier refactoring of comments between the
> out- and inline docs. But this is very minor, thus mixing two formats
> inside `Documentation/` does not seem like worth it.

FWIW, and this should be obvious, I think going with what's natural for
documenting Rust source code is the right choice. Markdown as parsed by
rustdoc. People will expect Rust documentation comments to just work,
without some kernel specific gotchas. Don't try to reinvent the wheel
here, it's a dead end.

The interesting question is, I think, figuring out if rustdoc output
could be incorporated into Sphinx documentation, and how. It would be
pretty disappointing if we ended up with two documentation silos based
on the module implementation language.

At the moment it seems to me rustdoc can only output HTML, and that
seems pretty deeply ingrained in the tool. AFAICT, there isn't an
intermediate phase where it would be trivial to output the documentation
in Markdown (though I don't really know Rust and I only had a cursory
look at librustdoc). And even if it were possible, with Markdown you'd
have the issues with conflicting Markdown flavours, what's supported by
rustdoc vs. commonmark.py used by Sphinx.

Perhaps the bare minimum is running rustdoc first, and generating the
results into Sphinx static pages [1], to make them part of the
whole. Even if the HTML style might be different. Perhaps it would be
possible to come up with a Sphinx extensions to make it convenient to
reference content in the rustdoc generated HTML from reStructuredText.


BR,
Jani.


[1] https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path


-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [PATCH] kernel-doc: better handle '::' sequences

[Miguel Ojeda]

On Tue, Mar 30, 2021 at 1:07 PM Jani Nikula <jani.nikula@linux.intel.com> wrote:
>
> FWIW, and this should be obvious, I think going with what's natural for
> documenting Rust source code is the right choice. Markdown as parsed by
> rustdoc. People will expect Rust documentation comments to just work,
> without some kernel specific gotchas. Don't try to reinvent the wheel
> here, it's a dead end.

Agreed!

> The interesting question is, I think, figuring out if rustdoc output
> could be incorporated into Sphinx documentation, and how. It would be
> pretty disappointing if we ended up with two documentation silos based
> on the module implementation language.

I want to have the Rust docs linked from Sphinx and uploaded as usual
to kernel.org etc.

However, please note that the implementation language implies a lot of
things, not just the "implementation language", if that makes sense.

For instance, if you write your module in Rust, the idea is that you
use the Rust infrastructure and exposed abstractions -- not that you
call C kernel functions on your own.

> At the moment it seems to me rustdoc can only output HTML, and that
> seems pretty deeply ingrained in the tool. AFAICT, there isn't an
> intermediate phase where it would be trivial to output the documentation
> in Markdown (though I don't really know Rust and I only had a cursory
> look at librustdoc). And even if it were possible, with Markdown you'd
> have the issues with conflicting Markdown flavours, what's supported by
> rustdoc vs. commonmark.py used by Sphinx.

Please note that `rustdoc` generates HTML that is intended for Rust
code, i.e. generating an intermediate format to then generate HTML
from Sphinx would make the Rust docs worse, unless the mapping is
perfect (but, at that point, why not just keep the standard Rust
docs?).

> Perhaps the bare minimum is running rustdoc first, and generating the
> results into Sphinx static pages [1], to make them part of the
> whole. Even if the HTML style might be different. Perhaps it would be

I don't think it is the "bare minimum", I think this is the optimal
solution! :-)

It is also not just about the style. The Rust docs are organized for
Rust code, the search functionality is meant for it, etc.

> possible to come up with a Sphinx extensions to make it convenient to
> reference content in the rustdoc generated HTML from reStructuredText.

For C -> Rust links, the plan I suggested to Jonathan was to have
Sphinx generate a text file with (reference, URL) pairs that then
`rustdoc` can use as links (e.g. to link to, say, the docs for
`printk`).

I also discussed it with the `rustdoc` maintainers, and they thought
it would be an interesting proposal, so I agreed to make an RFC for it
(note that it can be useful not just for Rust docs that need to refer
to C code, but also for any other kind of external content, e.g.
imagine a math library referencing a set of papers, books, etc.
without having to re-write the URL everywhere).

Cheers,
Miguel

[PATCH 7/8] of: Add missing 'Return' section in kerneldoc comments

[Rob Herring]

Many of the DT kerneldoc comments are lacking a 'Return' section. Let's
add the section in cases we have a description of return values. There's
still some cases where the return values are not documented.

Cc: Frank Rowand <frowand.list@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Rob Herring <robh@kernel.org>
---
 drivers/of/base.c     | 39 +++++++++++++------------
 drivers/of/dynamic.c  | 19 ++++++++-----
 drivers/of/fdt.c      |  8 +++---
 drivers/of/irq.c      | 14 ++++-----
 drivers/of/overlay.c  | 16 +++++------
 drivers/of/platform.c | 10 +++----
 drivers/of/property.c | 66 +++++++++++++++++++++++++++----------------
 include/linux/of.h    | 63 ++++++++++++++++++++++++++---------------
 8 files changed, 140 insertions(+), 95 deletions(-)

diff --git a/drivers/of/base.c b/drivers/of/base.c
index b06bcb3f001a..3bf189d394bd 100644
--- a/drivers/of/base.c
+++ b/drivers/of/base.c
@@ -244,7 +244,7 @@ struct device_node *__of_find_all_nodes(struct device_node *prev)
  * @prev:	Previous node or NULL to start iteration
  *		of_node_put() will be called on it
  *
- * Returns a node pointer with refcount incremented, use
+ * Return: A node pointer with refcount incremented, use
  * of_node_put() on it when done.
  */
 struct device_node *of_find_all_nodes(struct device_node *prev)
@@ -374,7 +374,7 @@ bool __weak arch_find_n_match_cpu_physical_id(struct device_node *cpun,
  * before booting secondary cores. This function uses arch_match_cpu_phys_id
  * which can be overridden by architecture specific implementation.
  *
- * Returns a node pointer for the logical cpu with refcount incremented, use
+ * Return: A node pointer for the logical cpu with refcount incremented, use
  * of_node_put() on it when done. Returns NULL if not found.
  */
 struct device_node *of_get_cpu_node(int cpu, unsigned int *thread)
@@ -394,8 +394,8 @@ EXPORT_SYMBOL(of_get_cpu_node);
  *
  * @cpu_node: Pointer to the device_node for CPU.
  *
- * Returns the logical CPU number of the given CPU device_node.
- * Returns -ENODEV if the CPU is not found.
+ * Return: The logical CPU number of the given CPU device_node or -ENODEV if the
+ * CPU is not found.
  */
 int of_cpu_node_to_id(struct device_node *cpu_node)
 {
@@ -427,7 +427,7 @@ EXPORT_SYMBOL(of_cpu_node_to_id);
  * bindings. This function check for both and returns the idle state node for
  * the requested index.
  *
- * In case an idle state node is found at @index, the refcount is incremented
+ * Return: An idle state node if found at @index. The refcount is incremented
  * for it, so call of_node_put() on it when done. Returns NULL if not found.
  */
 struct device_node *of_get_cpu_state_node(struct device_node *cpu_node,
@@ -561,7 +561,7 @@ int of_device_compatible_match(struct device_node *device,
  * of_machine_is_compatible - Test root of device tree for a given compatible value
  * @compat: compatible string to look for in root node's compatible property.
  *
- * Returns a positive integer if the root node has the given value in its
+ * Return: A positive integer if the root node has the given value in its
  * compatible property.
  */
 int of_machine_is_compatible(const char *compat)
@@ -583,7 +583,7 @@ EXPORT_SYMBOL(of_machine_is_compatible);
  *
  *  @device: Node to check for availability, with locks already held
  *
- *  Returns true if the status property is absent or set to "okay" or "ok",
+ *  Return: True if the status property is absent or set to "okay" or "ok",
  *  false otherwise
  */
 static bool __of_device_is_available(const struct device_node *device)
@@ -611,7 +611,7 @@ static bool __of_device_is_available(const struct device_node *device)
  *
  *  @device: Node to check for availability
  *
- *  Returns true if the status property is absent or set to "okay" or "ok",
+ *  Return: True if the status property is absent or set to "okay" or "ok",
  *  false otherwise
  */
 bool of_device_is_available(const struct device_node *device)
@@ -632,7 +632,7 @@ EXPORT_SYMBOL(of_device_is_available);
  *
  *  @device: Node to check for endianness
  *
- *  Returns true if the device has a "big-endian" property, or if the kernel
+ *  Return: True if the device has a "big-endian" property, or if the kernel
  *  was compiled for BE *and* the device has a "native-endian" property.
  *  Returns false otherwise.
  *
@@ -816,7 +816,7 @@ EXPORT_SYMBOL(of_get_next_cpu_node);
  * Lookup child node whose compatible property contains the given compatible
  * string.
  *
- * Returns a node pointer with refcount incremented, use of_node_put() on it
+ * Return: a node pointer with refcount incremented, use of_node_put() on it
  * when done; or NULL if not found.
  */
 struct device_node *of_get_compatible_child(const struct device_node *parent,
@@ -1170,7 +1170,7 @@ EXPORT_SYMBOL(of_find_matching_node_and_match);
  * It does this by stripping the manufacturer prefix (as delimited by a ',')
  * from the first entry in the compatible list property.
  *
- * This routine returns 0 on success, <0 on failure.
+ * Return: This routine returns 0 on success, <0 on failure.
  */
 int of_modalias_node(struct device_node *node, char *modalias, int len)
 {
@@ -1190,7 +1190,7 @@ EXPORT_SYMBOL_GPL(of_modalias_node);
  * of_find_node_by_phandle - Find a node given a phandle
  * @handle:	phandle of the node to find
  *
- * Returns a node pointer with refcount incremented, use
+ * Return: A node pointer with refcount incremented, use
  * of_node_put() on it when done.
  */
 struct device_node *of_find_node_by_phandle(phandle handle)
@@ -1426,7 +1426,7 @@ static int __of_parse_phandle_with_args(const struct device_node *np,
  * @index: For properties holding a table of phandles, this is the index into
  *         the table
  *
- * Returns the device_node pointer with refcount incremented.  Use
+ * Return: The device_node pointer with refcount incremented.  Use
  * of_node_put() on it when done.
  */
 struct device_node *of_parse_phandle(const struct device_node *np,
@@ -1725,7 +1725,7 @@ EXPORT_SYMBOL(of_parse_phandle_with_fixed_args);
  * @list_name:	property name that contains a list
  * @cells_name:	property name that specifies phandles' arguments count
  *
- * Returns the number of phandle + argument tuples within a property. It
+ * Return: The number of phandle + argument tuples within a property. It
  * is a typical pattern to encode a list of phandle and variable
  * arguments into a single property. The number of arguments is encoded
  * by a property in the phandle-target node. For example, a gpios
@@ -2025,7 +2025,9 @@ void of_alias_scan(void * (*dt_alloc)(u64 size, u64 align))
  * @stem:	Alias stem of the given device_node
  *
  * The function travels the lookup table to get the alias id for the given
- * device_node and alias stem.  It returns the alias id if found.
+ * device_node and alias stem.
+ *
+ * Return: The alias id if found.
  */
 int of_alias_get_id(struct device_node *np, const char *stem)
 {
@@ -2134,8 +2136,9 @@ EXPORT_SYMBOL_GPL(of_alias_get_highest_id);
  * @index: Index to use for preferred console.
  *
  * Check if the given device node matches the stdout-path property in the
- * /chosen node. If it does then register it as the preferred console and return
- * TRUE. Otherwise return FALSE.
+ * /chosen node. If it does then register it as the preferred console.
+ *
+ * Return: TRUE if console successfully setup. Otherwise return FALSE.
  */
 bool of_console_check(struct device_node *dn, char *name, int index)
 {
@@ -2186,7 +2189,7 @@ struct device_node *of_find_next_cache_node(const struct device_node *np)
  *
  * @cpu: cpu number(logical index) for which the last cache level is needed
  *
- * Returns the the level at which the last cache is present. It is exactly
+ * Return: The the level at which the last cache is present. It is exactly
  * same as  the total number of cache levels for the given logical cpu.
  */
 int of_find_last_cache_level(unsigned int cpu)
diff --git a/drivers/of/dynamic.c b/drivers/of/dynamic.c
index 1d7a22e44d78..cd3821a6444f 100644
--- a/drivers/of/dynamic.c
+++ b/drivers/of/dynamic.c
@@ -27,7 +27,7 @@ static struct device_node *kobj_to_device_node(struct kobject *kobj)
  * @node:	Node to inc refcount, NULL is supported to simplify writing of
  *		callers
  *
- * Returns node.
+ * Return: The node with refcount incremented.
  */
 struct device_node *of_node_get(struct device_node *node)
 {
@@ -104,7 +104,8 @@ int of_reconfig_notify(unsigned long action, struct of_reconfig_data *p)
  * @arg		- argument of the of notifier
  *
  * Returns the new state of a device based on the notifier used.
- * Returns 0 on device going from enabled to disabled, 1 on device
+ *
+ * Return: 0 on device going from enabled to disabled, 1 on device
  * going from disabled to enabled and -1 on no change.
  */
 int of_reconfig_get_state_change(unsigned long action, struct of_reconfig_data *pr)
@@ -374,7 +375,8 @@ void of_node_release(struct kobject *kobj)
  * property structure and the property name & contents. The property's
  * flags have the OF_DYNAMIC bit set so that we can differentiate between
  * dynamically allocated properties and not.
- * Returns the newly allocated property or NULL on out of memory error.
+ *
+ * Return: The newly allocated property or NULL on out of memory error.
  */
 struct property *__of_prop_dup(const struct property *prop, gfp_t allocflags)
 {
@@ -417,7 +419,7 @@ struct property *__of_prop_dup(const struct property *prop, gfp_t allocflags)
  * another node.  The node data are dynamically allocated and all the node
  * flags have the OF_DYNAMIC & OF_DETACHED bits set.
  *
- * Returns the newly allocated node or NULL on out of memory error.
+ * Return: The newly allocated node or NULL on out of memory error.
  */
 struct device_node *__of_node_dup(const struct device_node *np,
 				  const char *full_name)
@@ -783,7 +785,8 @@ static int __of_changeset_apply(struct of_changeset *ocs)
  * Any side-effects of live tree state changes are applied here on
  * success, like creation/destruction of devices and side-effects
  * like creation of sysfs properties and directories.
- * Returns 0 on success, a negative error value in case of an error.
+ *
+ * Return: 0 on success, a negative error value in case of an error.
  * On error the partially applied effects are reverted.
  */
 int of_changeset_apply(struct of_changeset *ocs)
@@ -877,7 +880,8 @@ static int __of_changeset_revert(struct of_changeset *ocs)
  * was before the application.
  * Any side-effects like creation/destruction of devices and
  * removal of sysfs properties and directories are applied.
- * Returns 0 on success, a negative error value in case of an error.
+ *
+ * Return: 0 on success, a negative error value in case of an error.
  */
 int of_changeset_revert(struct of_changeset *ocs)
 {
@@ -905,7 +909,8 @@ EXPORT_SYMBOL_GPL(of_changeset_revert);
  * + OF_RECONFIG_ADD_PROPERTY
  * + OF_RECONFIG_REMOVE_PROPERTY,
  * + OF_RECONFIG_UPDATE_PROPERTY
- * Returns 0 on success, a negative error value in case of an error.
+ *
+ * Return: 0 on success, a negative error value in case of an error.
  */
 int of_changeset_action(struct of_changeset *ocs, unsigned long action,
 		struct device_node *np, struct property *prop)
diff --git a/drivers/of/fdt.c b/drivers/of/fdt.c
index ba53da9c3895..134c7fb43a14 100644
--- a/drivers/of/fdt.c
+++ b/drivers/of/fdt.c
@@ -282,7 +282,7 @@ static void reverse_nodes(struct device_node *parent)
  * @dad: Parent struct device_node
  * @nodepp: The device_node tree created by the call
  *
- * It returns the size of unflattened device tree or error code
+ * Return: The size of unflattened device tree or error code
  */
 static int unflatten_dt_nodes(const void *blob,
 			      void *mem,
@@ -360,7 +360,7 @@ static int unflatten_dt_nodes(const void *blob,
  * fills the "name" and "type" pointers of the nodes so the normal device-tree
  * walking functions can be used.
  *
- * Returns NULL on failure or the memory chunk containing the unflattened
+ * Return: NULL on failure or the memory chunk containing the unflattened
  * device tree on success.
  */
 void *__unflatten_device_tree(const void *blob,
@@ -441,7 +441,7 @@ static DEFINE_MUTEX(of_fdt_unflatten_mutex);
  * pointers of the nodes so the normal device-tree walking functions
  * can be used.
  *
- * Returns NULL on failure or the memory chunk containing the unflattened
+ * Return: NULL on failure or the memory chunk containing the unflattened
  * device tree on success.
  */
 void *of_fdt_unflatten_tree(const unsigned long *blob,
@@ -716,7 +716,7 @@ const void *__init of_get_flat_dt_prop(unsigned long node, const char *name,
  * @node: node to test
  * @compat: compatible string to compare with compatible list.
  *
- * On match, returns a non-zero value with smaller values returned for more
+ * Return: a non-zero value on match with smaller values returned for more
  * specific compatible values.
  */
 static int of_fdt_is_compatible(const void *blob,
diff --git a/drivers/of/irq.c b/drivers/of/irq.c
index 25d17b8a1a1a..352e14b007e7 100644
--- a/drivers/of/irq.c
+++ b/drivers/of/irq.c
@@ -48,7 +48,7 @@ EXPORT_SYMBOL_GPL(irq_of_parse_and_map);
  * of_irq_find_parent - Given a device node, find its interrupt parent node
  * @child: pointer to device node
  *
- * Returns a pointer to the interrupt parent node, or NULL if the interrupt
+ * Return: A pointer to the interrupt parent node, or NULL if the interrupt
  * parent could not be determined.
  */
 struct device_node *of_irq_find_parent(struct device_node *child)
@@ -81,14 +81,14 @@ EXPORT_SYMBOL_GPL(of_irq_find_parent);
  * @addr:	address specifier (start of "reg" property of the device) in be32 format
  * @out_irq:	structure of_phandle_args updated by this function
  *
- * Returns 0 on success and a negative number on error
- *
  * This function is a low-level interrupt tree walking function. It
  * can be used to do a partial walk with synthetized reg and interrupts
  * properties, for example when resolving PCI interrupts when no device
  * node exist for the parent. It takes an interrupt specifier structure as
  * input, walks the tree looking for any interrupt-map properties, translates
  * the specifier for each map, and then returns the translated map.
+ *
+ * Return: 0 on success and a negative number on error
  */
 int of_irq_parse_raw(const __be32 *addr, struct of_phandle_args *out_irq)
 {
@@ -380,7 +380,7 @@ EXPORT_SYMBOL_GPL(of_irq_to_resource);
  * @dev: pointer to device tree node
  * @index: zero-based index of the IRQ
  *
- * Returns Linux IRQ number on success, or 0 on the IRQ mapping failure, or
+ * Return: Linux IRQ number on success, or 0 on the IRQ mapping failure, or
  * -EPROBE_DEFER if the IRQ domain is not yet created, or error code in case
  * of any other failure.
  */
@@ -407,7 +407,7 @@ EXPORT_SYMBOL_GPL(of_irq_get);
  * @dev: pointer to device tree node
  * @name: IRQ name
  *
- * Returns Linux IRQ number on success, or 0 on the IRQ mapping failure, or
+ * Return: Linux IRQ number on success, or 0 on the IRQ mapping failure, or
  * -EPROBE_DEFER if the IRQ domain is not yet created, or error code in case
  * of any other failure.
  */
@@ -447,7 +447,7 @@ int of_irq_count(struct device_node *dev)
  * @res: array of resources to fill in
  * @nr_irqs: the number of IRQs (and upper bound for num of @res elements)
  *
- * Returns the size of the filled in table (up to @nr_irqs).
+ * Return: The size of the filled in table (up to @nr_irqs).
  */
 int of_irq_to_resource_table(struct device_node *dev, struct resource *res,
 		int nr_irqs)
@@ -602,7 +602,7 @@ static u32 __of_msi_map_id(struct device *dev, struct device_node **np,
  * Walk up the device hierarchy looking for devices with a "msi-map"
  * property.  If found, apply the mapping to @id_in.
  *
- * Returns the mapped MSI ID.
+ * Return: The mapped MSI ID.
  */
 u32 of_msi_map_id(struct device *dev, struct device_node *msi_np, u32 id_in)
 {
diff --git a/drivers/of/overlay.c b/drivers/of/overlay.c
index c25679f7bd3f..d241273170fd 100644
--- a/drivers/of/overlay.c
+++ b/drivers/of/overlay.c
@@ -298,7 +298,7 @@ static struct property *dup_and_fixup_symbol_prop(
  *
  * Update of property in symbols node is not allowed.
  *
- * Returns 0 on success, -ENOMEM if memory allocation failure, or -EINVAL if
+ * Return: 0 on success, -ENOMEM if memory allocation failure, or -EINVAL if
  * invalid @overlay.
  */
 static int add_changeset_property(struct overlay_changeset *ovcs,
@@ -403,7 +403,7 @@ static int add_changeset_property(struct overlay_changeset *ovcs,
  *
  * NOTE_2: Multiple mods of created nodes not supported.
  *
- * Returns 0 on success, -ENOMEM if memory allocation failure, or -EINVAL if
+ * Return: 0 on success, -ENOMEM if memory allocation failure, or -EINVAL if
  * invalid @overlay.
  */
 static int add_changeset_node(struct overlay_changeset *ovcs,
@@ -475,7 +475,7 @@ static int add_changeset_node(struct overlay_changeset *ovcs,
  *
  * Do not allow symbols node to have any children.
  *
- * Returns 0 on success, -ENOMEM if memory allocation failure, or -EINVAL if
+ * Return: 0 on success, -ENOMEM if memory allocation failure, or -EINVAL if
  * invalid @overlay_node.
  */
 static int build_changeset_next_level(struct overlay_changeset *ovcs,
@@ -606,7 +606,7 @@ static int find_dup_cset_prop(struct overlay_changeset *ovcs,
  * the same node or duplicate {add, delete, or update} properties entries
  * for the same property.
  *
- * Returns 0 on success, or -EINVAL if duplicate changeset entry found.
+ * Return: 0 on success, or -EINVAL if duplicate changeset entry found.
  */
 static int changeset_dup_entry_check(struct overlay_changeset *ovcs)
 {
@@ -630,7 +630,7 @@ static int changeset_dup_entry_check(struct overlay_changeset *ovcs)
  * any portions of the changeset that were successfully created will remain
  * in @ovcs->cset.
  *
- * Returns 0 on success, -ENOMEM if memory allocation failure, or -EINVAL if
+ * Return: 0 on success, -ENOMEM if memory allocation failure, or -EINVAL if
  * invalid overlay in @ovcs->fragments[].
  */
 static int build_changeset(struct overlay_changeset *ovcs)
@@ -726,7 +726,7 @@ static struct device_node *find_target(struct device_node *info_node)
  * the top level of @tree.  The relevant top level nodes are the fragment
  * nodes and the __symbols__ node.  Any other top level node will be ignored.
  *
- * Returns 0 on success, -ENOMEM if memory allocation failure, -EINVAL if error
+ * Return: 0 on success, -ENOMEM if memory allocation failure, -EINVAL if error
  * detected in @tree, or -ENOSPC if idr_alloc() error.
  */
 static int init_overlay_changeset(struct overlay_changeset *ovcs,
@@ -1181,7 +1181,7 @@ static int overlay_removal_is_ok(struct overlay_changeset *remove_ovcs)
  * If an error is returned by an overlay changeset post-remove notifier
  * then no further overlay changeset post-remove notifier will be called.
  *
- * Returns 0 on success, or a negative error number.  *ovcs_id is set to
+ * Return: 0 on success, or a negative error number.  *ovcs_id is set to
  * zero after reverting the changeset, even if a subsequent error occurs.
  */
 int of_overlay_remove(int *ovcs_id)
@@ -1259,7 +1259,7 @@ EXPORT_SYMBOL_GPL(of_overlay_remove);
  *
  * Removes all overlays from the system in the correct order.
  *
- * Returns 0 on success, or a negative error number
+ * Return: 0 on success, or a negative error number
  */
 int of_overlay_remove_all(void)
 {
diff --git a/drivers/of/platform.c b/drivers/of/platform.c
index 0ed46d301431..25d448f5af91 100644
--- a/drivers/of/platform.c
+++ b/drivers/of/platform.c
@@ -44,7 +44,7 @@ static const struct of_device_id of_skipped_node_table[] = {
  * Takes a reference to the embedded struct device which needs to be dropped
  * after use.
  *
- * Returns platform_device pointer, or NULL if not found
+ * Return: platform_device pointer, or NULL if not found
  */
 struct platform_device *of_find_device_by_node(struct device_node *np)
 {
@@ -160,7 +160,7 @@ EXPORT_SYMBOL(of_device_alloc);
  * @platform_data: pointer to populate platform_data pointer with
  * @parent: Linux device model parent device.
  *
- * Returns pointer to created platform device, or NULL if a device was not
+ * Return: Pointer to created platform device, or NULL if a device was not
  * registered.  Unavailable devices will not get registered.
  */
 static struct platform_device *of_platform_device_create_pdata(
@@ -204,7 +204,7 @@ static struct platform_device *of_platform_device_create_pdata(
  * @bus_id: name to assign device
  * @parent: Linux device model parent device.
  *
- * Returns pointer to created platform device, or NULL if a device was not
+ * Return: Pointer to created platform device, or NULL if a device was not
  * registered.  Unavailable devices will not get registered.
  */
 struct platform_device *of_platform_device_create(struct device_node *np,
@@ -463,7 +463,7 @@ EXPORT_SYMBOL(of_platform_bus_probe);
  * New board support should be using this function instead of
  * of_platform_bus_probe().
  *
- * Returns 0 on success, < 0 on failure.
+ * Return: 0 on success, < 0 on failure.
  */
 int of_platform_populate(struct device_node *root,
 			const struct of_device_id *matches,
@@ -607,7 +607,7 @@ static void devm_of_platform_populate_release(struct device *dev, void *res)
  * Similar to of_platform_populate(), but will automatically call
  * of_platform_depopulate() when the device is unbound from the bus.
  *
- * Returns 0 on success, < 0 on failure.
+ * Return: 0 on success, < 0 on failure.
  */
 int devm_of_platform_populate(struct device *dev)
 {
diff --git a/drivers/of/property.c b/drivers/of/property.c
index c000ed01db01..2046ae311322 100644
--- a/drivers/of/property.c
+++ b/drivers/of/property.c
@@ -61,9 +61,11 @@ EXPORT_SYMBOL(of_graph_is_present);
  * @elem_size:	size of the individual element
  *
  * Search for a property in a device node and count the number of elements of
- * size elem_size in it. Returns number of elements on sucess, -EINVAL if the
- * property does not exist or its length does not match a multiple of elem_size
- * and -ENODATA if the property does not have a value.
+ * size elem_size in it.
+ *
+ * Return: The number of elements on sucess, -EINVAL if the property does not
+ * exist or its length does not match a multiple of elem_size and -ENODATA if
+ * the property does not have a value.
  */
 int of_property_count_elems_of_size(const struct device_node *np,
 				const char *propname, int elem_size)
@@ -95,8 +97,9 @@ EXPORT_SYMBOL_GPL(of_property_count_elems_of_size);
  * @len:	if !=NULL, actual length is written to here
  *
  * Search for a property in a device node and valid the requested size.
- * Returns the property value on success, -EINVAL if the property does not
- *  exist, -ENODATA if property does not have a value, and -EOVERFLOW if the
+ *
+ * Return: The property value on success, -EINVAL if the property does not
+ * exist, -ENODATA if property does not have a value, and -EOVERFLOW if the
  * property data is too small or too large.
  *
  */
@@ -129,7 +132,9 @@ static void *of_find_property_value_of_size(const struct device_node *np,
  * @out_value:	pointer to return value, modified only if no error.
  *
  * Search for a property in a device node and read nth 32-bit value from
- * it. Returns 0 on success, -EINVAL if the property does not exist,
+ * it.
+ *
+ * Return: 0 on success, -EINVAL if the property does not exist,
  * -ENODATA if property does not have a value, and -EOVERFLOW if the
  * property data isn't large enough.
  *
@@ -161,7 +166,9 @@ EXPORT_SYMBOL_GPL(of_property_read_u32_index);
  * @out_value:	pointer to return value, modified only if no error.
  *
  * Search for a property in a device node and read nth 64-bit value from
- * it. Returns 0 on success, -EINVAL if the property does not exist,
+ * it.
+ *
+ * Return: 0 on success, -EINVAL if the property does not exist,
  * -ENODATA if property does not have a value, and -EOVERFLOW if the
  * property data isn't large enough.
  *
@@ -196,12 +203,14 @@ EXPORT_SYMBOL_GPL(of_property_read_u64_index);
  *		sz_min will be read.
  *
  * Search for a property in a device node and read 8-bit value(s) from
- * it. Returns number of elements read on success, -EINVAL if the property
- * does not exist, -ENODATA if property does not have a value, and -EOVERFLOW
- * if the property data is smaller than sz_min or longer than sz_max.
+ * it.
  *
  * dts entry of array should be like:
- *	property = /bits/ 8 <0x50 0x60 0x70>;
+ *  ``property = /bits/ 8 <0x50 0x60 0x70>;``
+ *
+ * Return: The number of elements read on success, -EINVAL if the property
+ * does not exist, -ENODATA if property does not have a value, and -EOVERFLOW
+ * if the property data is smaller than sz_min or longer than sz_max.
  *
  * The out_values is modified only if a valid u8 value can be decoded.
  */
@@ -244,12 +253,14 @@ EXPORT_SYMBOL_GPL(of_property_read_variable_u8_array);
  *		sz_min will be read.
  *
  * Search for a property in a device node and read 16-bit value(s) from
- * it. Returns number of elements read on success, -EINVAL if the property
- * does not exist, -ENODATA if property does not have a value, and -EOVERFLOW
- * if the property data is smaller than sz_min or longer than sz_max.
+ * it.
  *
  * dts entry of array should be like:
- *	property = /bits/ 16 <0x5000 0x6000 0x7000>;
+ *  ``property = /bits/ 16 <0x5000 0x6000 0x7000>;``
+ *
+ * Return: The number of elements read on success, -EINVAL if the property
+ * does not exist, -ENODATA if property does not have a value, and -EOVERFLOW
+ * if the property data is smaller than sz_min or longer than sz_max.
  *
  * The out_values is modified only if a valid u16 value can be decoded.
  */
@@ -292,7 +303,9 @@ EXPORT_SYMBOL_GPL(of_property_read_variable_u16_array);
  *		sz_min will be read.
  *
  * Search for a property in a device node and read 32-bit value(s) from
- * it. Returns number of elements read on success, -EINVAL if the property
+ * it.
+ *
+ * Return: The number of elements read on success, -EINVAL if the property
  * does not exist, -ENODATA if property does not have a value, and -EOVERFLOW
  * if the property data is smaller than sz_min or longer than sz_max.
  *
@@ -331,7 +344,9 @@ EXPORT_SYMBOL_GPL(of_property_read_variable_u32_array);
  * @out_value:	pointer to return value, modified only if return value is 0.
  *
  * Search for a property in a device node and read a 64-bit value from
- * it. Returns 0 on success, -EINVAL if the property does not exist,
+ * it.
+ *
+ * Return: 0 on success, -EINVAL if the property does not exist,
  * -ENODATA if property does not have a value, and -EOVERFLOW if the
  * property data isn't large enough.
  *
@@ -366,7 +381,9 @@ EXPORT_SYMBOL_GPL(of_property_read_u64);
  *		sz_min will be read.
  *
  * Search for a property in a device node and read 64-bit value(s) from
- * it. Returns number of elements read on success, -EINVAL if the property
+ * it.
+ *
+ * Return: The number of elements read on success, -EINVAL if the property
  * does not exist, -ENODATA if property does not have a value, and -EOVERFLOW
  * if the property data is smaller than sz_min or longer than sz_max.
  *
@@ -408,10 +425,11 @@ EXPORT_SYMBOL_GPL(of_property_read_variable_u64_array);
  *		return value is 0.
  *
  * Search for a property in a device tree node and retrieve a null
- * terminated string value (pointer to data, not a copy). Returns 0 on
- * success, -EINVAL if the property does not exist, -ENODATA if property
- * does not have a value, and -EILSEQ if the string is not null-terminated
- * within the length of the property data.
+ * terminated string value (pointer to data, not a copy).
+ *
+ * Return: 0 on success, -EINVAL if the property does not exist, -ENODATA if
+ * property does not have a value, and -EILSEQ if the string is not
+ * null-terminated within the length of the property data.
  *
  * The out_string pointer is modified only if a valid string can be decoded.
  */
@@ -775,7 +793,7 @@ EXPORT_SYMBOL(of_graph_get_remote_port_parent);
  * @node: pointer to a local endpoint device_node
  *
  * Return: Remote port node associated with remote endpoint node linked
- *	   to @node. Use of_node_put() on it when done.
+ * to @node. Use of_node_put() on it when done.
  */
 struct device_node *of_graph_get_remote_port(const struct device_node *node)
 {
@@ -808,7 +826,7 @@ EXPORT_SYMBOL(of_graph_get_endpoint_count);
  * @endpoint: identifier (value of reg property) of the endpoint node
  *
  * Return: Remote device node associated with remote endpoint node linked
- *	   to @node. Use of_node_put() on it when done.
+ * to @node. Use of_node_put() on it when done.
  */
 struct device_node *of_graph_get_remote_node(const struct device_node *node,
 					     u32 port, u32 endpoint)
diff --git a/include/linux/of.h b/include/linux/of.h
index e9209ef44cc0..ef6b161d1f91 100644
--- a/include/linux/of.h
+++ b/include/linux/of.h
@@ -424,12 +424,14 @@ extern int of_detach_node(struct device_node *);
  * @sz:		number of array elements to read
  *
  * Search for a property in a device node and read 8-bit value(s) from
- * it. Returns 0 on success, -EINVAL if the property does not exist,
- * -ENODATA if property does not have a value, and -EOVERFLOW if the
- * property data isn't large enough.
+ * it.
  *
  * dts entry of array should be like:
- *	property = /bits/ 8 <0x50 0x60 0x70>;
+ *  ``property = /bits/ 8 <0x50 0x60 0x70>;``
+ *
+ * Return: 0 on success, -EINVAL if the property does not exist,
+ * -ENODATA if property does not have a value, and -EOVERFLOW if the
+ * property data isn't large enough.
  *
  * The out_values is modified only if a valid u8 value can be decoded.
  */
@@ -454,12 +456,14 @@ static inline int of_property_read_u8_array(const struct device_node *np,
  * @sz:		number of array elements to read
  *
  * Search for a property in a device node and read 16-bit value(s) from
- * it. Returns 0 on success, -EINVAL if the property does not exist,
- * -ENODATA if property does not have a value, and -EOVERFLOW if the
- * property data isn't large enough.
+ * it.
  *
  * dts entry of array should be like:
- *	property = /bits/ 16 <0x5000 0x6000 0x7000>;
+ *  ``property = /bits/ 16 <0x5000 0x6000 0x7000>;``
+ *
+ * Return: 0 on success, -EINVAL if the property does not exist,
+ * -ENODATA if property does not have a value, and -EOVERFLOW if the
+ * property data isn't large enough.
  *
  * The out_values is modified only if a valid u16 value can be decoded.
  */
@@ -485,7 +489,9 @@ static inline int of_property_read_u16_array(const struct device_node *np,
  * @sz:		number of array elements to read
  *
  * Search for a property in a device node and read 32-bit value(s) from
- * it. Returns 0 on success, -EINVAL if the property does not exist,
+ * it.
+ *
+ * Return: 0 on success, -EINVAL if the property does not exist,
  * -ENODATA if property does not have a value, and -EOVERFLOW if the
  * property data isn't large enough.
  *
@@ -513,7 +519,9 @@ static inline int of_property_read_u32_array(const struct device_node *np,
  * @sz:		number of array elements to read
  *
  * Search for a property in a device node and read 64-bit value(s) from
- * it. Returns 0 on success, -EINVAL if the property does not exist,
+ * it.
+ *
+ * Return: 0 on success, -EINVAL if the property does not exist,
  * -ENODATA if property does not have a value, and -EOVERFLOW if the
  * property data isn't large enough.
  *
@@ -1070,7 +1078,9 @@ static inline bool of_node_is_type(const struct device_node *np, const char *typ
  * @propname:	name of the property to be searched.
  *
  * Search for a property in a device node and count the number of u8 elements
- * in it. Returns number of elements on sucess, -EINVAL if the property does
+ * in it.
+ *
+ * Return: The number of elements on sucess, -EINVAL if the property does
  * not exist or its length does not match a multiple of u8 and -ENODATA if the
  * property does not have a value.
  */
@@ -1087,7 +1097,9 @@ static inline int of_property_count_u8_elems(const struct device_node *np,
  * @propname:	name of the property to be searched.
  *
  * Search for a property in a device node and count the number of u16 elements
- * in it. Returns number of elements on sucess, -EINVAL if the property does
+ * in it.
+ *
+ * Return: The number of elements on sucess, -EINVAL if the property does
  * not exist or its length does not match a multiple of u16 and -ENODATA if the
  * property does not have a value.
  */
@@ -1104,7 +1116,9 @@ static inline int of_property_count_u16_elems(const struct device_node *np,
  * @propname:	name of the property to be searched.
  *
  * Search for a property in a device node and count the number of u32 elements
- * in it. Returns number of elements on sucess, -EINVAL if the property does
+ * in it.
+ *
+ * Return: The number of elements on sucess, -EINVAL if the property does
  * not exist or its length does not match a multiple of u32 and -ENODATA if the
  * property does not have a value.
  */
@@ -1121,7 +1135,9 @@ static inline int of_property_count_u32_elems(const struct device_node *np,
  * @propname:	name of the property to be searched.
  *
  * Search for a property in a device node and count the number of u64 elements
- * in it. Returns number of elements on sucess, -EINVAL if the property does
+ * in it.
+ *
+ * Return: The number of elements on sucess, -EINVAL if the property does
  * not exist or its length does not match a multiple of u64 and -ENODATA if the
  * property does not have a value.
  */
@@ -1142,7 +1158,7 @@ static inline int of_property_count_u64_elems(const struct device_node *np,
  * Search for a property in a device tree node and retrieve a list of
  * terminated string values (pointer to data, not a copy) in that property.
  *
- * If @out_strs is NULL, the number of strings in the property is returned.
+ * Return: If @out_strs is NULL, the number of strings in the property is returned.
  */
 static inline int of_property_read_string_array(const struct device_node *np,
 						const char *propname, const char **out_strs,
@@ -1158,10 +1174,11 @@ static inline int of_property_read_string_array(const struct device_node *np,
  * @propname:	name of the property to be searched.
  *
  * Search for a property in a device tree node and retrieve the number of null
- * terminated string contain in it. Returns the number of strings on
- * success, -EINVAL if the property does not exist, -ENODATA if property
- * does not have a value, and -EILSEQ if the string is not null-terminated
- * within the length of the property data.
+ * terminated string contain in it.
+ *
+ * Return: The number of strings on success, -EINVAL if the property does not
+ * exist, -ENODATA if property does not have a value, and -EILSEQ if the string
+ * is not null-terminated within the length of the property data.
  */
 static inline int of_property_count_strings(const struct device_node *np,
 					    const char *propname)
@@ -1181,7 +1198,8 @@ static inline int of_property_count_strings(const struct device_node *np,
  * Search for a property in a device tree node and retrieve a null
  * terminated string value (pointer to data, not a copy) in the list of strings
  * contained in that property.
- * Returns 0 on success, -EINVAL if the property does not exist, -ENODATA if
+ *
+ * Return: 0 on success, -EINVAL if the property does not exist, -ENODATA if
  * property does not have a value, and -EILSEQ if the string is not
  * null-terminated within the length of the property data.
  *
@@ -1201,7 +1219,8 @@ static inline int of_property_read_string_index(const struct device_node *np,
  * @propname:	name of the property to be searched.
  *
  * Search for a property in a device node.
- * Returns true if the property exists false otherwise.
+ *
+ * Return: true if the property exists false otherwise.
  */
 static inline bool of_property_read_bool(const struct device_node *np,
 					 const char *propname)
@@ -1447,7 +1466,7 @@ static inline int of_reconfig_get_state_change(unsigned long action,
  * of_device_is_system_power_controller - Tells if system-power-controller is found for device_node
  * @np: Pointer to the given device_node
  *
- * return true if present false otherwise
+ * Return: true if present false otherwise
  */
 static inline bool of_device_is_system_power_controller(const struct device_node *np)
 {
-- 
2.27.0

Re: [PATCH 7/8] of: Add missing 'Return' section in kerneldoc comments

[Mauro Carvalho Chehab]

Em Thu, 25 Mar 2021 10:47:12 -0600
Rob Herring <robh@kernel.org> escreveu:

> Many of the DT kerneldoc comments are lacking a 'Return' section. Let's
> add the section in cases we have a description of return values. There's
> still some cases where the return values are not documented.
> 
> Cc: Frank Rowand <frowand.list@gmail.com>
> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

> Signed-off-by: Rob Herring <robh@kernel.org>
> ---
>  drivers/of/base.c     | 39 +++++++++++++------------
>  drivers/of/dynamic.c  | 19 ++++++++-----
>  drivers/of/fdt.c      |  8 +++---
>  drivers/of/irq.c      | 14 ++++-----
>  drivers/of/overlay.c  | 16 +++++------
>  drivers/of/platform.c | 10 +++----
>  drivers/of/property.c | 66 +++++++++++++++++++++++++++----------------
>  include/linux/of.h    | 63 ++++++++++++++++++++++++++---------------
>  8 files changed, 140 insertions(+), 95 deletions(-)
> 
> diff --git a/drivers/of/base.c b/drivers/of/base.c
> index b06bcb3f001a..3bf189d394bd 100644
> --- a/drivers/of/base.c
> +++ b/drivers/of/base.c
> @@ -244,7 +244,7 @@ struct device_node *__of_find_all_nodes(struct device_node *prev)
>   * @prev:	Previous node or NULL to start iteration
>   *		of_node_put() will be called on it
>   *
> - * Returns a node pointer with refcount incremented, use
> + * Return: A node pointer with refcount incremented, use
>   * of_node_put() on it when done.
>   */
>  struct device_node *of_find_all_nodes(struct device_node *prev)
> @@ -374,7 +374,7 @@ bool __weak arch_find_n_match_cpu_physical_id(struct device_node *cpun,
>   * before booting secondary cores. This function uses arch_match_cpu_phys_id
>   * which can be overridden by architecture specific implementation.
>   *
> - * Returns a node pointer for the logical cpu with refcount incremented, use
> + * Return: A node pointer for the logical cpu with refcount incremented, use
>   * of_node_put() on it when done. Returns NULL if not found.
>   */
>  struct device_node *of_get_cpu_node(int cpu, unsigned int *thread)
> @@ -394,8 +394,8 @@ EXPORT_SYMBOL(of_get_cpu_node);
>   *
>   * @cpu_node: Pointer to the device_node for CPU.
>   *
> - * Returns the logical CPU number of the given CPU device_node.
> - * Returns -ENODEV if the CPU is not found.
> + * Return: The logical CPU number of the given CPU device_node or -ENODEV if the
> + * CPU is not found.
>   */
>  int of_cpu_node_to_id(struct device_node *cpu_node)
>  {
> @@ -427,7 +427,7 @@ EXPORT_SYMBOL(of_cpu_node_to_id);
>   * bindings. This function check for both and returns the idle state node for
>   * the requested index.
>   *
> - * In case an idle state node is found at @index, the refcount is incremented
> + * Return: An idle state node if found at @index. The refcount is incremented
>   * for it, so call of_node_put() on it when done. Returns NULL if not found.
>   */
>  struct device_node *of_get_cpu_state_node(struct device_node *cpu_node,
> @@ -561,7 +561,7 @@ int of_device_compatible_match(struct device_node *device,
>   * of_machine_is_compatible - Test root of device tree for a given compatible value
>   * @compat: compatible string to look for in root node's compatible property.
>   *
> - * Returns a positive integer if the root node has the given value in its
> + * Return: A positive integer if the root node has the given value in its
>   * compatible property.
>   */
>  int of_machine_is_compatible(const char *compat)
> @@ -583,7 +583,7 @@ EXPORT_SYMBOL(of_machine_is_compatible);
>   *
>   *  @device: Node to check for availability, with locks already held
>   *
> - *  Returns true if the status property is absent or set to "okay" or "ok",
> + *  Return: True if the status property is absent or set to "okay" or "ok",
>   *  false otherwise
>   */
>  static bool __of_device_is_available(const struct device_node *device)
> @@ -611,7 +611,7 @@ static bool __of_device_is_available(const struct device_node *device)
>   *
>   *  @device: Node to check for availability
>   *
> - *  Returns true if the status property is absent or set to "okay" or "ok",
> + *  Return: True if the status property is absent or set to "okay" or "ok",
>   *  false otherwise
>   */
>  bool of_device_is_available(const struct device_node *device)
> @@ -632,7 +632,7 @@ EXPORT_SYMBOL(of_device_is_available);
>   *
>   *  @device: Node to check for endianness
>   *
> - *  Returns true if the device has a "big-endian" property, or if the kernel
> + *  Return: True if the device has a "big-endian" property, or if the kernel
>   *  was compiled for BE *and* the device has a "native-endian" property.
>   *  Returns false otherwise.
>   *
> @@ -816,7 +816,7 @@ EXPORT_SYMBOL(of_get_next_cpu_node);
>   * Lookup child node whose compatible property contains the given compatible
>   * string.
>   *
> - * Returns a node pointer with refcount incremented, use of_node_put() on it
> + * Return: a node pointer with refcount incremented, use of_node_put() on it
>   * when done; or NULL if not found.
>   */
>  struct device_node *of_get_compatible_child(const struct device_node *parent,
> @@ -1170,7 +1170,7 @@ EXPORT_SYMBOL(of_find_matching_node_and_match);
>   * It does this by stripping the manufacturer prefix (as delimited by a ',')
>   * from the first entry in the compatible list property.
>   *
> - * This routine returns 0 on success, <0 on failure.
> + * Return: This routine returns 0 on success, <0 on failure.
>   */
>  int of_modalias_node(struct device_node *node, char *modalias, int len)
>  {
> @@ -1190,7 +1190,7 @@ EXPORT_SYMBOL_GPL(of_modalias_node);
>   * of_find_node_by_phandle - Find a node given a phandle
>   * @handle:	phandle of the node to find
>   *
> - * Returns a node pointer with refcount incremented, use
> + * Return: A node pointer with refcount incremented, use
>   * of_node_put() on it when done.
>   */
>  struct device_node *of_find_node_by_phandle(phandle handle)
> @@ -1426,7 +1426,7 @@ static int __of_parse_phandle_with_args(const struct device_node *np,
>   * @index: For properties holding a table of phandles, this is the index into
>   *         the table
>   *
> - * Returns the device_node pointer with refcount incremented.  Use
> + * Return: The device_node pointer with refcount incremented.  Use
>   * of_node_put() on it when done.
>   */
>  struct device_node *of_parse_phandle(const struct device_node *np,
> @@ -1725,7 +1725,7 @@ EXPORT_SYMBOL(of_parse_phandle_with_fixed_args);
>   * @list_name:	property name that contains a list
>   * @cells_name:	property name that specifies phandles' arguments count
>   *
> - * Returns the number of phandle + argument tuples within a property. It
> + * Return: The number of phandle + argument tuples within a property. It
>   * is a typical pattern to encode a list of phandle and variable
>   * arguments into a single property. The number of arguments is encoded
>   * by a property in the phandle-target node. For example, a gpios
> @@ -2025,7 +2025,9 @@ void of_alias_scan(void * (*dt_alloc)(u64 size, u64 align))
>   * @stem:	Alias stem of the given device_node
>   *
>   * The function travels the lookup table to get the alias id for the given
> - * device_node and alias stem.  It returns the alias id if found.
> + * device_node and alias stem.
> + *
> + * Return: The alias id if found.
>   */
>  int of_alias_get_id(struct device_node *np, const char *stem)
>  {
> @@ -2134,8 +2136,9 @@ EXPORT_SYMBOL_GPL(of_alias_get_highest_id);
>   * @index: Index to use for preferred console.
>   *
>   * Check if the given device node matches the stdout-path property in the
> - * /chosen node. If it does then register it as the preferred console and return
> - * TRUE. Otherwise return FALSE.
> + * /chosen node. If it does then register it as the preferred console.
> + *
> + * Return: TRUE if console successfully setup. Otherwise return FALSE.
>   */
>  bool of_console_check(struct device_node *dn, char *name, int index)
>  {
> @@ -2186,7 +2189,7 @@ struct device_node *of_find_next_cache_node(const struct device_node *np)
>   *
>   * @cpu: cpu number(logical index) for which the last cache level is needed
>   *
> - * Returns the the level at which the last cache is present. It is exactly
> + * Return: The the level at which the last cache is present. It is exactly
>   * same as  the total number of cache levels for the given logical cpu.
>   */
>  int of_find_last_cache_level(unsigned int cpu)
> diff --git a/drivers/of/dynamic.c b/drivers/of/dynamic.c
> index 1d7a22e44d78..cd3821a6444f 100644
> --- a/drivers/of/dynamic.c
> +++ b/drivers/of/dynamic.c
> @@ -27,7 +27,7 @@ static struct device_node *kobj_to_device_node(struct kobject *kobj)
>   * @node:	Node to inc refcount, NULL is supported to simplify writing of
>   *		callers
>   *
> - * Returns node.
> + * Return: The node with refcount incremented.
>   */
>  struct device_node *of_node_get(struct device_node *node)
>  {
> @@ -104,7 +104,8 @@ int of_reconfig_notify(unsigned long action, struct of_reconfig_data *p)
>   * @arg		- argument of the of notifier
>   *
>   * Returns the new state of a device based on the notifier used.
> - * Returns 0 on device going from enabled to disabled, 1 on device
> + *
> + * Return: 0 on device going from enabled to disabled, 1 on device
>   * going from disabled to enabled and -1 on no change.
>   */
>  int of_reconfig_get_state_change(unsigned long action, struct of_reconfig_data *pr)
> @@ -374,7 +375,8 @@ void of_node_release(struct kobject *kobj)
>   * property structure and the property name & contents. The property's
>   * flags have the OF_DYNAMIC bit set so that we can differentiate between
>   * dynamically allocated properties and not.
> - * Returns the newly allocated property or NULL on out of memory error.
> + *
> + * Return: The newly allocated property or NULL on out of memory error.
>   */
>  struct property *__of_prop_dup(const struct property *prop, gfp_t allocflags)
>  {
> @@ -417,7 +419,7 @@ struct property *__of_prop_dup(const struct property *prop, gfp_t allocflags)
>   * another node.  The node data are dynamically allocated and all the node
>   * flags have the OF_DYNAMIC & OF_DETACHED bits set.
>   *
> - * Returns the newly allocated node or NULL on out of memory error.
> + * Return: The newly allocated node or NULL on out of memory error.
>   */
>  struct device_node *__of_node_dup(const struct device_node *np,
>  				  const char *full_name)
> @@ -783,7 +785,8 @@ static int __of_changeset_apply(struct of_changeset *ocs)
>   * Any side-effects of live tree state changes are applied here on
>   * success, like creation/destruction of devices and side-effects
>   * like creation of sysfs properties and directories.
> - * Returns 0 on success, a negative error value in case of an error.
> + *
> + * Return: 0 on success, a negative error value in case of an error.
>   * On error the partially applied effects are reverted.
>   */
>  int of_changeset_apply(struct of_changeset *ocs)
> @@ -877,7 +880,8 @@ static int __of_changeset_revert(struct of_changeset *ocs)
>   * was before the application.
>   * Any side-effects like creation/destruction of devices and
>   * removal of sysfs properties and directories are applied.
> - * Returns 0 on success, a negative error value in case of an error.
> + *
> + * Return: 0 on success, a negative error value in case of an error.
>   */
>  int of_changeset_revert(struct of_changeset *ocs)
>  {
> @@ -905,7 +909,8 @@ EXPORT_SYMBOL_GPL(of_changeset_revert);
>   * + OF_RECONFIG_ADD_PROPERTY
>   * + OF_RECONFIG_REMOVE_PROPERTY,
>   * + OF_RECONFIG_UPDATE_PROPERTY
> - * Returns 0 on success, a negative error value in case of an error.
> + *
> + * Return: 0 on success, a negative error value in case of an error.
>   */
>  int of_changeset_action(struct of_changeset *ocs, unsigned long action,
>  		struct device_node *np, struct property *prop)
> diff --git a/drivers/of/fdt.c b/drivers/of/fdt.c
> index ba53da9c3895..134c7fb43a14 100644
> --- a/drivers/of/fdt.c
> +++ b/drivers/of/fdt.c
> @@ -282,7 +282,7 @@ static void reverse_nodes(struct device_node *parent)
>   * @dad: Parent struct device_node
>   * @nodepp: The device_node tree created by the call
>   *
> - * It returns the size of unflattened device tree or error code
> + * Return: The size of unflattened device tree or error code
>   */
>  static int unflatten_dt_nodes(const void *blob,
>  			      void *mem,
> @@ -360,7 +360,7 @@ static int unflatten_dt_nodes(const void *blob,
>   * fills the "name" and "type" pointers of the nodes so the normal device-tree
>   * walking functions can be used.
>   *
> - * Returns NULL on failure or the memory chunk containing the unflattened
> + * Return: NULL on failure or the memory chunk containing the unflattened
>   * device tree on success.
>   */
>  void *__unflatten_device_tree(const void *blob,
> @@ -441,7 +441,7 @@ static DEFINE_MUTEX(of_fdt_unflatten_mutex);
>   * pointers of the nodes so the normal device-tree walking functions
>   * can be used.
>   *
> - * Returns NULL on failure or the memory chunk containing the unflattened
> + * Return: NULL on failure or the memory chunk containing the unflattened
>   * device tree on success.
>   */
>  void *of_fdt_unflatten_tree(const unsigned long *blob,
> @@ -716,7 +716,7 @@ const void *__init of_get_flat_dt_prop(unsigned long node, const char *name,
>   * @node: node to test
>   * @compat: compatible string to compare with compatible list.
>   *
> - * On match, returns a non-zero value with smaller values returned for more
> + * Return: a non-zero value on match with smaller values returned for more
>   * specific compatible values.
>   */
>  static int of_fdt_is_compatible(const void *blob,
> diff --git a/drivers/of/irq.c b/drivers/of/irq.c
> index 25d17b8a1a1a..352e14b007e7 100644
> --- a/drivers/of/irq.c
> +++ b/drivers/of/irq.c
> @@ -48,7 +48,7 @@ EXPORT_SYMBOL_GPL(irq_of_parse_and_map);
>   * of_irq_find_parent - Given a device node, find its interrupt parent node
>   * @child: pointer to device node
>   *
> - * Returns a pointer to the interrupt parent node, or NULL if the interrupt
> + * Return: A pointer to the interrupt parent node, or NULL if the interrupt
>   * parent could not be determined.
>   */
>  struct device_node *of_irq_find_parent(struct device_node *child)
> @@ -81,14 +81,14 @@ EXPORT_SYMBOL_GPL(of_irq_find_parent);
>   * @addr:	address specifier (start of "reg" property of the device) in be32 format
>   * @out_irq:	structure of_phandle_args updated by this function
>   *
> - * Returns 0 on success and a negative number on error
> - *
>   * This function is a low-level interrupt tree walking function. It
>   * can be used to do a partial walk with synthetized reg and interrupts
>   * properties, for example when resolving PCI interrupts when no device
>   * node exist for the parent. It takes an interrupt specifier structure as
>   * input, walks the tree looking for any interrupt-map properties, translates
>   * the specifier for each map, and then returns the translated map.
> + *
> + * Return: 0 on success and a negative number on error
>   */
>  int of_irq_parse_raw(const __be32 *addr, struct of_phandle_args *out_irq)
>  {
> @@ -380,7 +380,7 @@ EXPORT_SYMBOL_GPL(of_irq_to_resource);
>   * @dev: pointer to device tree node
>   * @index: zero-based index of the IRQ
>   *
> - * Returns Linux IRQ number on success, or 0 on the IRQ mapping failure, or
> + * Return: Linux IRQ number on success, or 0 on the IRQ mapping failure, or
>   * -EPROBE_DEFER if the IRQ domain is not yet created, or error code in case
>   * of any other failure.
>   */
> @@ -407,7 +407,7 @@ EXPORT_SYMBOL_GPL(of_irq_get);
>   * @dev: pointer to device tree node
>   * @name: IRQ name
>   *
> - * Returns Linux IRQ number on success, or 0 on the IRQ mapping failure, or
> + * Return: Linux IRQ number on success, or 0 on the IRQ mapping failure, or
>   * -EPROBE_DEFER if the IRQ domain is not yet created, or error code in case
>   * of any other failure.
>   */
> @@ -447,7 +447,7 @@ int of_irq_count(struct device_node *dev)
>   * @res: array of resources to fill in
>   * @nr_irqs: the number of IRQs (and upper bound for num of @res elements)
>   *
> - * Returns the size of the filled in table (up to @nr_irqs).
> + * Return: The size of the filled in table (up to @nr_irqs).
>   */
>  int of_irq_to_resource_table(struct device_node *dev, struct resource *res,
>  		int nr_irqs)
> @@ -602,7 +602,7 @@ static u32 __of_msi_map_id(struct device *dev, struct device_node **np,
>   * Walk up the device hierarchy looking for devices with a "msi-map"
>   * property.  If found, apply the mapping to @id_in.
>   *
> - * Returns the mapped MSI ID.
> + * Return: The mapped MSI ID.
>   */
>  u32 of_msi_map_id(struct device *dev, struct device_node *msi_np, u32 id_in)
>  {
> diff --git a/drivers/of/overlay.c b/drivers/of/overlay.c
> index c25679f7bd3f..d241273170fd 100644
> --- a/drivers/of/overlay.c
> +++ b/drivers/of/overlay.c
> @@ -298,7 +298,7 @@ static struct property *dup_and_fixup_symbol_prop(
>   *
>   * Update of property in symbols node is not allowed.
>   *
> - * Returns 0 on success, -ENOMEM if memory allocation failure, or -EINVAL if
> + * Return: 0 on success, -ENOMEM if memory allocation failure, or -EINVAL if
>   * invalid @overlay.
>   */
>  static int add_changeset_property(struct overlay_changeset *ovcs,
> @@ -403,7 +403,7 @@ static int add_changeset_property(struct overlay_changeset *ovcs,
>   *
>   * NOTE_2: Multiple mods of created nodes not supported.
>   *
> - * Returns 0 on success, -ENOMEM if memory allocation failure, or -EINVAL if
> + * Return: 0 on success, -ENOMEM if memory allocation failure, or -EINVAL if
>   * invalid @overlay.
>   */
>  static int add_changeset_node(struct overlay_changeset *ovcs,
> @@ -475,7 +475,7 @@ static int add_changeset_node(struct overlay_changeset *ovcs,
>   *
>   * Do not allow symbols node to have any children.
>   *
> - * Returns 0 on success, -ENOMEM if memory allocation failure, or -EINVAL if
> + * Return: 0 on success, -ENOMEM if memory allocation failure, or -EINVAL if
>   * invalid @overlay_node.
>   */
>  static int build_changeset_next_level(struct overlay_changeset *ovcs,
> @@ -606,7 +606,7 @@ static int find_dup_cset_prop(struct overlay_changeset *ovcs,
>   * the same node or duplicate {add, delete, or update} properties entries
>   * for the same property.
>   *
> - * Returns 0 on success, or -EINVAL if duplicate changeset entry found.
> + * Return: 0 on success, or -EINVAL if duplicate changeset entry found.
>   */
>  static int changeset_dup_entry_check(struct overlay_changeset *ovcs)
>  {
> @@ -630,7 +630,7 @@ static int changeset_dup_entry_check(struct overlay_changeset *ovcs)
>   * any portions of the changeset that were successfully created will remain
>   * in @ovcs->cset.
>   *
> - * Returns 0 on success, -ENOMEM if memory allocation failure, or -EINVAL if
> + * Return: 0 on success, -ENOMEM if memory allocation failure, or -EINVAL if
>   * invalid overlay in @ovcs->fragments[].
>   */
>  static int build_changeset(struct overlay_changeset *ovcs)
> @@ -726,7 +726,7 @@ static struct device_node *find_target(struct device_node *info_node)
>   * the top level of @tree.  The relevant top level nodes are the fragment
>   * nodes and the __symbols__ node.  Any other top level node will be ignored.
>   *
> - * Returns 0 on success, -ENOMEM if memory allocation failure, -EINVAL if error
> + * Return: 0 on success, -ENOMEM if memory allocation failure, -EINVAL if error
>   * detected in @tree, or -ENOSPC if idr_alloc() error.
>   */
>  static int init_overlay_changeset(struct overlay_changeset *ovcs,
> @@ -1181,7 +1181,7 @@ static int overlay_removal_is_ok(struct overlay_changeset *remove_ovcs)
>   * If an error is returned by an overlay changeset post-remove notifier
>   * then no further overlay changeset post-remove notifier will be called.
>   *
> - * Returns 0 on success, or a negative error number.  *ovcs_id is set to
> + * Return: 0 on success, or a negative error number.  *ovcs_id is set to
>   * zero after reverting the changeset, even if a subsequent error occurs.
>   */
>  int of_overlay_remove(int *ovcs_id)
> @@ -1259,7 +1259,7 @@ EXPORT_SYMBOL_GPL(of_overlay_remove);
>   *
>   * Removes all overlays from the system in the correct order.
>   *
> - * Returns 0 on success, or a negative error number
> + * Return: 0 on success, or a negative error number
>   */
>  int of_overlay_remove_all(void)
>  {
> diff --git a/drivers/of/platform.c b/drivers/of/platform.c
> index 0ed46d301431..25d448f5af91 100644
> --- a/drivers/of/platform.c
> +++ b/drivers/of/platform.c
> @@ -44,7 +44,7 @@ static const struct of_device_id of_skipped_node_table[] = {
>   * Takes a reference to the embedded struct device which needs to be dropped
>   * after use.
>   *
> - * Returns platform_device pointer, or NULL if not found
> + * Return: platform_device pointer, or NULL if not found
>   */
>  struct platform_device *of_find_device_by_node(struct device_node *np)
>  {
> @@ -160,7 +160,7 @@ EXPORT_SYMBOL(of_device_alloc);
>   * @platform_data: pointer to populate platform_data pointer with
>   * @parent: Linux device model parent device.
>   *
> - * Returns pointer to created platform device, or NULL if a device was not
> + * Return: Pointer to created platform device, or NULL if a device was not
>   * registered.  Unavailable devices will not get registered.
>   */
>  static struct platform_device *of_platform_device_create_pdata(
> @@ -204,7 +204,7 @@ static struct platform_device *of_platform_device_create_pdata(
>   * @bus_id: name to assign device
>   * @parent: Linux device model parent device.
>   *
> - * Returns pointer to created platform device, or NULL if a device was not
> + * Return: Pointer to created platform device, or NULL if a device was not
>   * registered.  Unavailable devices will not get registered.
>   */
>  struct platform_device *of_platform_device_create(struct device_node *np,
> @@ -463,7 +463,7 @@ EXPORT_SYMBOL(of_platform_bus_probe);
>   * New board support should be using this function instead of
>   * of_platform_bus_probe().
>   *
> - * Returns 0 on success, < 0 on failure.
> + * Return: 0 on success, < 0 on failure.
>   */
>  int of_platform_populate(struct device_node *root,
>  			const struct of_device_id *matches,
> @@ -607,7 +607,7 @@ static void devm_of_platform_populate_release(struct device *dev, void *res)
>   * Similar to of_platform_populate(), but will automatically call
>   * of_platform_depopulate() when the device is unbound from the bus.
>   *
> - * Returns 0 on success, < 0 on failure.
> + * Return: 0 on success, < 0 on failure.
>   */
>  int devm_of_platform_populate(struct device *dev)
>  {
> diff --git a/drivers/of/property.c b/drivers/of/property.c
> index c000ed01db01..2046ae311322 100644
> --- a/drivers/of/property.c
> +++ b/drivers/of/property.c
> @@ -61,9 +61,11 @@ EXPORT_SYMBOL(of_graph_is_present);
>   * @elem_size:	size of the individual element
>   *
>   * Search for a property in a device node and count the number of elements of
> - * size elem_size in it. Returns number of elements on sucess, -EINVAL if the
> - * property does not exist or its length does not match a multiple of elem_size
> - * and -ENODATA if the property does not have a value.
> + * size elem_size in it.
> + *
> + * Return: The number of elements on sucess, -EINVAL if the property does not
> + * exist or its length does not match a multiple of elem_size and -ENODATA if
> + * the property does not have a value.
>   */
>  int of_property_count_elems_of_size(const struct device_node *np,
>  				const char *propname, int elem_size)
> @@ -95,8 +97,9 @@ EXPORT_SYMBOL_GPL(of_property_count_elems_of_size);
>   * @len:	if !=NULL, actual length is written to here
>   *
>   * Search for a property in a device node and valid the requested size.
> - * Returns the property value on success, -EINVAL if the property does not
> - *  exist, -ENODATA if property does not have a value, and -EOVERFLOW if the
> + *
> + * Return: The property value on success, -EINVAL if the property does not
> + * exist, -ENODATA if property does not have a value, and -EOVERFLOW if the
>   * property data is too small or too large.
>   *
>   */
> @@ -129,7 +132,9 @@ static void *of_find_property_value_of_size(const struct device_node *np,
>   * @out_value:	pointer to return value, modified only if no error.
>   *
>   * Search for a property in a device node and read nth 32-bit value from
> - * it. Returns 0 on success, -EINVAL if the property does not exist,
> + * it.
> + *
> + * Return: 0 on success, -EINVAL if the property does not exist,
>   * -ENODATA if property does not have a value, and -EOVERFLOW if the
>   * property data isn't large enough.
>   *
> @@ -161,7 +166,9 @@ EXPORT_SYMBOL_GPL(of_property_read_u32_index);
>   * @out_value:	pointer to return value, modified only if no error.
>   *
>   * Search for a property in a device node and read nth 64-bit value from
> - * it. Returns 0 on success, -EINVAL if the property does not exist,
> + * it.
> + *
> + * Return: 0 on success, -EINVAL if the property does not exist,
>   * -ENODATA if property does not have a value, and -EOVERFLOW if the
>   * property data isn't large enough.
>   *
> @@ -196,12 +203,14 @@ EXPORT_SYMBOL_GPL(of_property_read_u64_index);
>   *		sz_min will be read.
>   *
>   * Search for a property in a device node and read 8-bit value(s) from
> - * it. Returns number of elements read on success, -EINVAL if the property
> - * does not exist, -ENODATA if property does not have a value, and -EOVERFLOW
> - * if the property data is smaller than sz_min or longer than sz_max.
> + * it.
>   *
>   * dts entry of array should be like:
> - *	property = /bits/ 8 <0x50 0x60 0x70>;
> + *  ``property = /bits/ 8 <0x50 0x60 0x70>;``
> + *
> + * Return: The number of elements read on success, -EINVAL if the property
> + * does not exist, -ENODATA if property does not have a value, and -EOVERFLOW
> + * if the property data is smaller than sz_min or longer than sz_max.
>   *
>   * The out_values is modified only if a valid u8 value can be decoded.
>   */
> @@ -244,12 +253,14 @@ EXPORT_SYMBOL_GPL(of_property_read_variable_u8_array);
>   *		sz_min will be read.
>   *
>   * Search for a property in a device node and read 16-bit value(s) from
> - * it. Returns number of elements read on success, -EINVAL if the property
> - * does not exist, -ENODATA if property does not have a value, and -EOVERFLOW
> - * if the property data is smaller than sz_min or longer than sz_max.
> + * it.
>   *
>   * dts entry of array should be like:
> - *	property = /bits/ 16 <0x5000 0x6000 0x7000>;
> + *  ``property = /bits/ 16 <0x5000 0x6000 0x7000>;``
> + *
> + * Return: The number of elements read on success, -EINVAL if the property
> + * does not exist, -ENODATA if property does not have a value, and -EOVERFLOW
> + * if the property data is smaller than sz_min or longer than sz_max.
>   *
>   * The out_values is modified only if a valid u16 value can be decoded.
>   */
> @@ -292,7 +303,9 @@ EXPORT_SYMBOL_GPL(of_property_read_variable_u16_array);
>   *		sz_min will be read.
>   *
>   * Search for a property in a device node and read 32-bit value(s) from
> - * it. Returns number of elements read on success, -EINVAL if the property
> + * it.
> + *
> + * Return: The number of elements read on success, -EINVAL if the property
>   * does not exist, -ENODATA if property does not have a value, and -EOVERFLOW
>   * if the property data is smaller than sz_min or longer than sz_max.
>   *
> @@ -331,7 +344,9 @@ EXPORT_SYMBOL_GPL(of_property_read_variable_u32_array);
>   * @out_value:	pointer to return value, modified only if return value is 0.
>   *
>   * Search for a property in a device node and read a 64-bit value from
> - * it. Returns 0 on success, -EINVAL if the property does not exist,
> + * it.
> + *
> + * Return: 0 on success, -EINVAL if the property does not exist,
>   * -ENODATA if property does not have a value, and -EOVERFLOW if the
>   * property data isn't large enough.
>   *
> @@ -366,7 +381,9 @@ EXPORT_SYMBOL_GPL(of_property_read_u64);
>   *		sz_min will be read.
>   *
>   * Search for a property in a device node and read 64-bit value(s) from
> - * it. Returns number of elements read on success, -EINVAL if the property
> + * it.
> + *
> + * Return: The number of elements read on success, -EINVAL if the property
>   * does not exist, -ENODATA if property does not have a value, and -EOVERFLOW
>   * if the property data is smaller than sz_min or longer than sz_max.
>   *
> @@ -408,10 +425,11 @@ EXPORT_SYMBOL_GPL(of_property_read_variable_u64_array);
>   *		return value is 0.
>   *
>   * Search for a property in a device tree node and retrieve a null
> - * terminated string value (pointer to data, not a copy). Returns 0 on
> - * success, -EINVAL if the property does not exist, -ENODATA if property
> - * does not have a value, and -EILSEQ if the string is not null-terminated
> - * within the length of the property data.
> + * terminated string value (pointer to data, not a copy).
> + *
> + * Return: 0 on success, -EINVAL if the property does not exist, -ENODATA if
> + * property does not have a value, and -EILSEQ if the string is not
> + * null-terminated within the length of the property data.
>   *
>   * The out_string pointer is modified only if a valid string can be decoded.
>   */
> @@ -775,7 +793,7 @@ EXPORT_SYMBOL(of_graph_get_remote_port_parent);
>   * @node: pointer to a local endpoint device_node
>   *
>   * Return: Remote port node associated with remote endpoint node linked
> - *	   to @node. Use of_node_put() on it when done.
> + * to @node. Use of_node_put() on it when done.
>   */
>  struct device_node *of_graph_get_remote_port(const struct device_node *node)
>  {
> @@ -808,7 +826,7 @@ EXPORT_SYMBOL(of_graph_get_endpoint_count);
>   * @endpoint: identifier (value of reg property) of the endpoint node
>   *
>   * Return: Remote device node associated with remote endpoint node linked
> - *	   to @node. Use of_node_put() on it when done.
> + * to @node. Use of_node_put() on it when done.
>   */
>  struct device_node *of_graph_get_remote_node(const struct device_node *node,
>  					     u32 port, u32 endpoint)
> diff --git a/include/linux/of.h b/include/linux/of.h
> index e9209ef44cc0..ef6b161d1f91 100644
> --- a/include/linux/of.h
> +++ b/include/linux/of.h
> @@ -424,12 +424,14 @@ extern int of_detach_node(struct device_node *);
>   * @sz:		number of array elements to read
>   *
>   * Search for a property in a device node and read 8-bit value(s) from
> - * it. Returns 0 on success, -EINVAL if the property does not exist,
> - * -ENODATA if property does not have a value, and -EOVERFLOW if the
> - * property data isn't large enough.
> + * it.
>   *
>   * dts entry of array should be like:
> - *	property = /bits/ 8 <0x50 0x60 0x70>;
> + *  ``property = /bits/ 8 <0x50 0x60 0x70>;``
> + *
> + * Return: 0 on success, -EINVAL if the property does not exist,
> + * -ENODATA if property does not have a value, and -EOVERFLOW if the
> + * property data isn't large enough.
>   *
>   * The out_values is modified only if a valid u8 value can be decoded.
>   */
> @@ -454,12 +456,14 @@ static inline int of_property_read_u8_array(const struct device_node *np,
>   * @sz:		number of array elements to read
>   *
>   * Search for a property in a device node and read 16-bit value(s) from
> - * it. Returns 0 on success, -EINVAL if the property does not exist,
> - * -ENODATA if property does not have a value, and -EOVERFLOW if the
> - * property data isn't large enough.
> + * it.
>   *
>   * dts entry of array should be like:
> - *	property = /bits/ 16 <0x5000 0x6000 0x7000>;
> + *  ``property = /bits/ 16 <0x5000 0x6000 0x7000>;``
> + *
> + * Return: 0 on success, -EINVAL if the property does not exist,
> + * -ENODATA if property does not have a value, and -EOVERFLOW if the
> + * property data isn't large enough.
>   *
>   * The out_values is modified only if a valid u16 value can be decoded.
>   */
> @@ -485,7 +489,9 @@ static inline int of_property_read_u16_array(const struct device_node *np,
>   * @sz:		number of array elements to read
>   *
>   * Search for a property in a device node and read 32-bit value(s) from
> - * it. Returns 0 on success, -EINVAL if the property does not exist,
> + * it.
> + *
> + * Return: 0 on success, -EINVAL if the property does not exist,
>   * -ENODATA if property does not have a value, and -EOVERFLOW if the
>   * property data isn't large enough.
>   *
> @@ -513,7 +519,9 @@ static inline int of_property_read_u32_array(const struct device_node *np,
>   * @sz:		number of array elements to read
>   *
>   * Search for a property in a device node and read 64-bit value(s) from
> - * it. Returns 0 on success, -EINVAL if the property does not exist,
> + * it.
> + *
> + * Return: 0 on success, -EINVAL if the property does not exist,
>   * -ENODATA if property does not have a value, and -EOVERFLOW if the
>   * property data isn't large enough.
>   *
> @@ -1070,7 +1078,9 @@ static inline bool of_node_is_type(const struct device_node *np, const char *typ
>   * @propname:	name of the property to be searched.
>   *
>   * Search for a property in a device node and count the number of u8 elements
> - * in it. Returns number of elements on sucess, -EINVAL if the property does
> + * in it.
> + *
> + * Return: The number of elements on sucess, -EINVAL if the property does
>   * not exist or its length does not match a multiple of u8 and -ENODATA if the
>   * property does not have a value.
>   */
> @@ -1087,7 +1097,9 @@ static inline int of_property_count_u8_elems(const struct device_node *np,
>   * @propname:	name of the property to be searched.
>   *
>   * Search for a property in a device node and count the number of u16 elements
> - * in it. Returns number of elements on sucess, -EINVAL if the property does
> + * in it.
> + *
> + * Return: The number of elements on sucess, -EINVAL if the property does
>   * not exist or its length does not match a multiple of u16 and -ENODATA if the
>   * property does not have a value.
>   */
> @@ -1104,7 +1116,9 @@ static inline int of_property_count_u16_elems(const struct device_node *np,
>   * @propname:	name of the property to be searched.
>   *
>   * Search for a property in a device node and count the number of u32 elements
> - * in it. Returns number of elements on sucess, -EINVAL if the property does
> + * in it.
> + *
> + * Return: The number of elements on sucess, -EINVAL if the property does
>   * not exist or its length does not match a multiple of u32 and -ENODATA if the
>   * property does not have a value.
>   */
> @@ -1121,7 +1135,9 @@ static inline int of_property_count_u32_elems(const struct device_node *np,
>   * @propname:	name of the property to be searched.
>   *
>   * Search for a property in a device node and count the number of u64 elements
> - * in it. Returns number of elements on sucess, -EINVAL if the property does
> + * in it.
> + *
> + * Return: The number of elements on sucess, -EINVAL if the property does
>   * not exist or its length does not match a multiple of u64 and -ENODATA if the
>   * property does not have a value.
>   */
> @@ -1142,7 +1158,7 @@ static inline int of_property_count_u64_elems(const struct device_node *np,
>   * Search for a property in a device tree node and retrieve a list of
>   * terminated string values (pointer to data, not a copy) in that property.
>   *
> - * If @out_strs is NULL, the number of strings in the property is returned.
> + * Return: If @out_strs is NULL, the number of strings in the property is returned.
>   */
>  static inline int of_property_read_string_array(const struct device_node *np,
>  						const char *propname, const char **out_strs,
> @@ -1158,10 +1174,11 @@ static inline int of_property_read_string_array(const struct device_node *np,
>   * @propname:	name of the property to be searched.
>   *
>   * Search for a property in a device tree node and retrieve the number of null
> - * terminated string contain in it. Returns the number of strings on
> - * success, -EINVAL if the property does not exist, -ENODATA if property
> - * does not have a value, and -EILSEQ if the string is not null-terminated
> - * within the length of the property data.
> + * terminated string contain in it.
> + *
> + * Return: The number of strings on success, -EINVAL if the property does not
> + * exist, -ENODATA if property does not have a value, and -EILSEQ if the string
> + * is not null-terminated within the length of the property data.
>   */
>  static inline int of_property_count_strings(const struct device_node *np,
>  					    const char *propname)
> @@ -1181,7 +1198,8 @@ static inline int of_property_count_strings(const struct device_node *np,
>   * Search for a property in a device tree node and retrieve a null
>   * terminated string value (pointer to data, not a copy) in the list of strings
>   * contained in that property.
> - * Returns 0 on success, -EINVAL if the property does not exist, -ENODATA if
> + *
> + * Return: 0 on success, -EINVAL if the property does not exist, -ENODATA if
>   * property does not have a value, and -EILSEQ if the string is not
>   * null-terminated within the length of the property data.
>   *
> @@ -1201,7 +1219,8 @@ static inline int of_property_read_string_index(const struct device_node *np,
>   * @propname:	name of the property to be searched.
>   *
>   * Search for a property in a device node.
> - * Returns true if the property exists false otherwise.
> + *
> + * Return: true if the property exists false otherwise.
>   */
>  static inline bool of_property_read_bool(const struct device_node *np,
>  					 const char *propname)
> @@ -1447,7 +1466,7 @@ static inline int of_reconfig_get_state_change(unsigned long action,
>   * of_device_is_system_power_controller - Tells if system-power-controller is found for device_node
>   * @np: Pointer to the given device_node
>   *
> - * return true if present false otherwise
> + * Return: true if present false otherwise
>   */
>  static inline bool of_device_is_system_power_controller(const struct device_node *np)
>  {



Thanks,
Mauro

[PATCH 8/8] docs: dt: Add DT API documentation

[Rob Herring]

The kernel-doc for the DT APIs are not included in the documentation
build. Add them.

Cc: Frank Rowand <frowand.list@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Rob Herring <robh@kernel.org>
---
 Documentation/devicetree/index.rst      |  1 +
 Documentation/devicetree/kernel-api.rst | 57 +++++++++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 Documentation/devicetree/kernel-api.rst

diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
index 70b5dcdbcf07..1a2fc8014996 100644
--- a/Documentation/devicetree/index.rst
+++ b/Documentation/devicetree/index.rst
@@ -11,6 +11,7 @@ Kernel Devicetree Usage
 
    usage-model
    of_unittest
+   kernel-api
 
 Devicetree Overlays
 ===================
diff --git a/Documentation/devicetree/kernel-api.rst b/Documentation/devicetree/kernel-api.rst
new file mode 100644
index 000000000000..b7429e6ed6d5
--- /dev/null
+++ b/Documentation/devicetree/kernel-api.rst
@@ -0,0 +1,57 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. _devicetree:
+
+======================================
+DeviceTree Kernel API
+======================================
+
+Core functions
+--------------
+
+.. kernel-doc:: drivers/of/base.c
+   :export:
+
+.. kernel-doc:: include/linux/of.h
+   :internal:
+
+.. kernel-doc:: drivers/of/property.c
+   :export:
+
+.. kernel-doc:: include/linux/of_graph.h
+   :internal:
+
+.. kernel-doc:: drivers/of/address.c
+   :export:
+
+.. kernel-doc:: drivers/of/irq.c
+   :export:
+
+.. kernel-doc:: drivers/of/fdt.c
+   :export:
+
+Driver model functions
+----------------------
+
+.. kernel-doc:: include/linux/of_device.h
+   :internal:
+
+.. kernel-doc:: drivers/of/device.c
+   :export:
+
+.. kernel-doc:: include/linux/of_platform.h
+   :internal:
+
+.. kernel-doc:: drivers/of/platform.c
+   :export:
+
+Overlay and Dynamic DT functions
+--------------------------------
+
+.. kernel-doc:: drivers/of/resolver.c
+   :export:
+
+.. kernel-doc:: drivers/of/dynamic.c
+   :export:
+
+.. kernel-doc:: drivers/of/overlay.c
+   :export:
-- 
2.27.0

Re: [PATCH 8/8] docs: dt: Add DT API documentation

[Mauro Carvalho Chehab]

Em Thu, 25 Mar 2021 10:47:13 -0600
Rob Herring <robh@kernel.org> escreveu:

> The kernel-doc for the DT APIs are not included in the documentation
> build. Add them.
> 
> Cc: Frank Rowand <frowand.list@gmail.com>
> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

> Signed-off-by: Rob Herring <robh@kernel.org>
> ---
>  Documentation/devicetree/index.rst      |  1 +
>  Documentation/devicetree/kernel-api.rst | 57 +++++++++++++++++++++++++
>  2 files changed, 58 insertions(+)
>  create mode 100644 Documentation/devicetree/kernel-api.rst
> 
> diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
> index 70b5dcdbcf07..1a2fc8014996 100644
> --- a/Documentation/devicetree/index.rst
> +++ b/Documentation/devicetree/index.rst
> @@ -11,6 +11,7 @@ Kernel Devicetree Usage
>  
>     usage-model
>     of_unittest
> +   kernel-api
>  
>  Devicetree Overlays
>  ===================
> diff --git a/Documentation/devicetree/kernel-api.rst b/Documentation/devicetree/kernel-api.rst
> new file mode 100644
> index 000000000000..b7429e6ed6d5
> --- /dev/null
> +++ b/Documentation/devicetree/kernel-api.rst
> @@ -0,0 +1,57 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. _devicetree:
> +
> +======================================
> +DeviceTree Kernel API
> +======================================
> +
> +Core functions
> +--------------
> +
> +.. kernel-doc:: drivers/of/base.c
> +   :export:
> +
> +.. kernel-doc:: include/linux/of.h
> +   :internal:
> +
> +.. kernel-doc:: drivers/of/property.c
> +   :export:
> +
> +.. kernel-doc:: include/linux/of_graph.h
> +   :internal:
> +
> +.. kernel-doc:: drivers/of/address.c
> +   :export:
> +
> +.. kernel-doc:: drivers/of/irq.c
> +   :export:
> +
> +.. kernel-doc:: drivers/of/fdt.c
> +   :export:
> +
> +Driver model functions
> +----------------------
> +
> +.. kernel-doc:: include/linux/of_device.h
> +   :internal:
> +
> +.. kernel-doc:: drivers/of/device.c
> +   :export:
> +
> +.. kernel-doc:: include/linux/of_platform.h
> +   :internal:
> +
> +.. kernel-doc:: drivers/of/platform.c
> +   :export:
> +
> +Overlay and Dynamic DT functions
> +--------------------------------
> +
> +.. kernel-doc:: drivers/of/resolver.c
> +   :export:
> +
> +.. kernel-doc:: drivers/of/dynamic.c
> +   :export:
> +
> +.. kernel-doc:: drivers/of/overlay.c
> +   :export:



Thanks,
Mauro