[PATCH 1/9] doc: add include/dm/uclass.h to the HTML documentation

[PATCH 1/9] doc: add include/dm/uclass.h to the HTML documentation

[Patrick Delaunay]

Correct Sphinx style comments in include/dm/uclass.h
and add the driver model UCLASS API to the HTML documentation.

Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
---

 doc/api/dm.rst      |  9 ++++++
 doc/api/index.rst   |  1 +
 include/dm/uclass.h | 75 ++++++++++++++++++++++-----------------------
 3 files changed, 47 insertions(+), 38 deletions(-)
 create mode 100644 doc/api/dm.rst

diff --git a/doc/api/dm.rst b/doc/api/dm.rst
new file mode 100644
index 0000000000..edce25da51
--- /dev/null
+++ b/doc/api/dm.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Driver Model
+============
+
+Uclass and Driver
+-----------------
+
+.. kernel-doc:: include/dm/uclass.h
diff --git a/doc/api/index.rst b/doc/api/index.rst
index 806c7385a6..3f36174167 100644
--- a/doc/api/index.rst
+++ b/doc/api/index.rst
@@ -7,6 +7,7 @@ U-Boot API documentation
    :maxdepth: 2
 
    dfu
+   dm
    efi
    getopt
    linker_lists
diff --git a/include/dm/uclass.h b/include/dm/uclass.h
index f1fd2ba246..a12a872d94 100644
--- a/include/dm/uclass.h
+++ b/include/dm/uclass.h
@@ -84,7 +84,7 @@ struct udevice;
  * its children. If non-zero this is the size of this data, to be allocated
  * in the child device's parent_plat pointer. This value is only used as
  * a fallback if this member is 0 in the driver.
- * @flags: Flags for this uclass (DM_UC_...)
+ * @flags: Flags for this uclass ``(DM_UC_...)``
  */
 struct uclass_driver {
 	const char *name;
@@ -127,17 +127,16 @@ struct uclass_driver {
  * build time. Before this is used, an extern UCLASS_DRIVER() must have been
  * declared.
  *
- * For example:
+ * For example: ::
  *
- * extern UCLASS_DRIVER(clk);
- *
- * struct uclass_driver *drvs[] = {
- *	DM_UCLASS_DRIVER_REF(clk),
- * };
+ *   extern UCLASS_DRIVER(clk);
+ *   struct uclass_driver *drvs[] = {
+ *       DM_UCLASS_DRIVER_REF(clk),
+ *   };
  *
  * @_name: Name of the uclass_driver. This must be a valid C identifier, used by
  *	the linker_list.
- * @returns struct uclass_driver * for the uclass driver
+ * Return: struct uclass_driver * for the uclass driver
  */
 #define DM_UCLASS_DRIVER_REF(_name)					\
 	ll_entry_ref(struct uclass_driver, _name, uclass_driver)
@@ -145,8 +144,8 @@ struct uclass_driver {
 /**
  * uclass_get_priv() - Get the private data for a uclass
  *
- * @uc		Uclass to check
- * @return private data, or NULL if none
+ * @uc:	Uclass to check
+ * Return: private data, or NULL if none
  */
 void *uclass_get_priv(const struct uclass *uc);
 
@@ -159,8 +158,8 @@ void *uclass_get_priv(const struct uclass *uc);
  *
  * @key: ID to look up
  * @ucp: Returns pointer to uclass (there is only one per ID)
- * @return 0 if OK, -EDEADLK if driver model is not yet inited, other -ve on
- *	other error
+ * Return: 0 if OK, -EDEADLK if driver model is not yet inited, other -ve on
+ * other error
  */
 int uclass_get(enum uclass_id key, struct uclass **ucp);
 
@@ -168,16 +167,16 @@ int uclass_get(enum uclass_id key, struct uclass **ucp);
  * uclass_get_name() - Get the name of a uclass driver
  *
  * @id: ID to look up
- * @returns the name of the uclass driver for that ID, or NULL if none
+ * Return: the name of the uclass driver for that ID, or NULL if none
  */
 const char *uclass_get_name(enum uclass_id id);
 
 /**
- * uclass_get_by_name() - Look up a uclass by its driver name
+ * uclass_get_by_name_len() - Look up a uclass by its partial driver name
  *
  * @name: Name to look up
- * @len: Length of name
- * @returns the associated uclass ID, or UCLASS_INVALID if not found
+ * @len: Length of the partial name
+ * Return: the associated uclass ID, or UCLASS_INVALID if not found
  */
 enum uclass_id uclass_get_by_name_len(const char *name, int len);
 
@@ -185,7 +184,7 @@ enum uclass_id uclass_get_by_name_len(const char *name, int len);
  * uclass_get_by_name() - Look up a uclass by its driver name
  *
  * @name: Name to look up
- * @returns the associated uclass ID, or UCLASS_INVALID if not found
+ * Return: the associated uclass ID, or UCLASS_INVALID if not found
  */
 enum uclass_id uclass_get_by_name(const char *name);
 
@@ -197,7 +196,7 @@ enum uclass_id uclass_get_by_name(const char *name);
  * @id: ID to look up
  * @index: Device number within that uclass (0=first)
  * @devp: Returns pointer to device (there is only one per for each ID)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int uclass_get_device(enum uclass_id id, int index, struct udevice **devp);
 
@@ -211,7 +210,7 @@ int uclass_get_device(enum uclass_id id, int index, struct udevice **devp);
  * @id: ID to look up
  * @name: name of a device to get
  * @devp: Returns pointer to device (the first one with the name)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int uclass_get_device_by_name(enum uclass_id id, const char *name,
 			      struct udevice **devp);
@@ -228,7 +227,7 @@ int uclass_get_device_by_name(enum uclass_id id, const char *name,
  * @id: ID to look up
  * @seq: Sequence number to find (0=first)
  * @devp: Returns pointer to device (there is only one for each seq)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int uclass_get_device_by_seq(enum uclass_id id, int seq, struct udevice **devp);
 
@@ -243,7 +242,7 @@ int uclass_get_device_by_seq(enum uclass_id id, int seq, struct udevice **devp);
  * @id: ID to look up
  * @node: Device tree offset to search for (if -ve then -ENODEV is returned)
  * @devp: Returns pointer to device (there is only one for each node)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int uclass_get_device_by_of_offset(enum uclass_id id, int node,
 				   struct udevice **devp);
@@ -257,9 +256,9 @@ int uclass_get_device_by_of_offset(enum uclass_id id, int node,
  * The device is probed to activate it ready for use.
  *
  * @id: ID to look up
- * @np: Device tree node to search for (if NULL then -ENODEV is returned)
+ * @node: Device tree node to search for (if NULL then -ENODEV is returned)
  * @devp: Returns pointer to device (there is only one for each node)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int uclass_get_device_by_ofnode(enum uclass_id id, ofnode node,
 				struct udevice **devp);
@@ -275,8 +274,8 @@ int uclass_get_device_by_ofnode(enum uclass_id id, ofnode node,
  * @phandle_id: the phandle id to look up
  * @devp: Returns pointer to device (there is only one for each node). NULL if
  *	there is no such device.
- * @return 0 if OK, -ENODEV if there is no device match the phandle, other
- *	-ve on error
+ * Return: 0 if OK, -ENODEV if there is no device match the phandle, other
+ * -ve on error
  */
 int uclass_get_device_by_phandle_id(enum uclass_id id, uint phandle_id,
 				    struct udevice **devp);
@@ -292,8 +291,8 @@ int uclass_get_device_by_phandle_id(enum uclass_id id, uint phandle_id,
  * @parent: Parent device containing the phandle pointer
  * @name: Name of property in the parent device node
  * @devp: Returns pointer to device (there is only one for each node)
- * @return 0 if OK, -ENOENT if there is no @name present in the node, other
- *	-ve on error
+ * Return: 0 if OK, -ENOENT if there is no @name present in the node, other
+ * -ve on error
  */
 int uclass_get_device_by_phandle(enum uclass_id id, struct udevice *parent,
 				 const char *name, struct udevice **devp);
@@ -310,7 +309,7 @@ int uclass_get_device_by_phandle(enum uclass_id id, struct udevice *parent,
  * @id: ID to look up
  * @drv: Driver to look for
  * @devp: Returns pointer to the first device with that driver
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int uclass_get_device_by_driver(enum uclass_id id, const struct driver *drv,
 				struct udevice **devp);
@@ -327,7 +326,7 @@ int uclass_get_device_by_driver(enum uclass_id id, const struct driver *drv,
  * @devp: Returns pointer to the first device in that uclass if no error
  * occurred, or NULL if there is no first device, or an error occurred with
  * that device.
- * @return 0 if OK (found or not found), other -ve on error
+ * Return: 0 if OK (found or not found), other -ve on error
  */
 int uclass_first_device(enum uclass_id id, struct udevice **devp);
 
@@ -338,7 +337,7 @@ int uclass_first_device(enum uclass_id id, struct udevice **devp);
  *
  * @id: Uclass ID to look up
  * @devp: Returns pointer to the first device in that uclass, or NULL if none
- * @return 0 if found, -ENODEV if not found, other -ve on error
+ * Return: 0 if found, -ENODEV if not found, other -ve on error
  */
 int uclass_first_device_err(enum uclass_id id, struct udevice **devp);
 
@@ -353,7 +352,7 @@ int uclass_first_device_err(enum uclass_id id, struct udevice **devp);
  * @devp: On entry, pointer to device to lookup. On exit, returns pointer
  * to the next device in the uclass if no error occurred, or NULL if there is
  * no next device, or an error occurred with that next device.
- * @return 0 if OK (found or not found), other -ve on error
+ * Return: 0 if OK (found or not found), other -ve on error
  */
 int uclass_next_device(struct udevice **devp);
 
@@ -365,7 +364,7 @@ int uclass_next_device(struct udevice **devp);
  * @devp: On entry, pointer to device to lookup. On exit, returns pointer
  * to the next device in the uclass if no error occurred, or NULL if
  * there is no next device.
- * @return 0 if found, -ENODEV if not found, other -ve on error
+ * Return: 0 if found, -ENODEV if not found, other -ve on error
  */
 int uclass_next_device_err(struct udevice **devp);
 
@@ -380,7 +379,7 @@ int uclass_next_device_err(struct udevice **devp);
  * @id: Uclass ID to look up
  * @devp: Returns pointer to the first device in that uclass, or NULL if there
  * is no first device
- * @return 0 if OK (found or not found), other -ve on error. If an error occurs
+ * Return: 0 if OK (found or not found), other -ve on error. If an error occurs
  * it is still possible to move to the next device.
  */
 int uclass_first_device_check(enum uclass_id id, struct udevice **devp);
@@ -395,7 +394,7 @@ int uclass_first_device_check(enum uclass_id id, struct udevice **devp);
  *
  * @devp: On entry, pointer to device to lookup. On exit, returns pointer
  * to the next device in the uclass if any
- * @return 0 if OK (found or not found), other -ve on error. If an error occurs
+ * Return: 0 if OK (found or not found), other -ve on error. If an error occurs
  * it is still possible to move to the next device.
  */
 int uclass_next_device_check(struct udevice **devp);
@@ -409,7 +408,7 @@ int uclass_next_device_check(struct udevice **devp);
  * @id: Uclass ID to check
  * @driver_data: Driver data to search for
  * @devp: Returns pointer to the first matching device in that uclass, if found
- * @return 0 if found, -ENODEV if not found, other -ve on error
+ * Return: 0 if found, -ENODEV if not found, other -ve on error
  */
 int uclass_first_device_drvdata(enum uclass_id id, ulong driver_data,
 				struct udevice **devp);
@@ -421,7 +420,7 @@ int uclass_first_device_drvdata(enum uclass_id id, ulong driver_data,
  * looking for its ID.
  *
  * @id: uclass ID to look up
- * @return 0 if OK, other -ve on error
+ * Return: 0 if OK, other -ve on error
  */
 int uclass_probe_all(enum uclass_id id);
 
@@ -429,7 +428,7 @@ int uclass_probe_all(enum uclass_id id);
  * uclass_id_count() - Count the number of devices in a uclass
  *
  * @id: uclass ID to look up
- * @return number of devices in that uclass (0 if none)
+ * Return: number of devices in that uclass (0 if none)
  */
 int uclass_id_count(enum uclass_id id);
 
@@ -444,7 +443,7 @@ int uclass_id_count(enum uclass_id id);
  * @id: enum uclass_id ID to use
  * @pos: struct udevice * to hold the current device. Set to NULL when there
  * are no more devices.
- * @uc: temporary uclass variable (struct uclass *)
+ * @uc: temporary uclass variable (``struct uclass *``)
  */
 #define uclass_id_foreach_dev(id, pos, uc) \
 	if (!uclass_get(id, &uc)) \
-- 
2.25.1

[PATCH 2/9] doc: add include/dm/root.h to the HTML documentation

[Patrick Delaunay]

Correct Sphinx style comments in include/dm/devres.h
and add the associated driver model API to the HTML documentation.

Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
---

 doc/api/dm.rst    |  1 +
 include/dm/root.h | 20 +++++++++++---------
 2 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/doc/api/dm.rst b/doc/api/dm.rst
index edce25da51..181a454c24 100644
--- a/doc/api/dm.rst
+++ b/doc/api/dm.rst
@@ -7,3 +7,4 @@ Uclass and Driver
 -----------------
 
 .. kernel-doc:: include/dm/uclass.h
+.. kernel-doc:: include/dm/root.h
diff --git a/include/dm/root.h b/include/dm/root.h
index 780f269db6..e888fb993c 100644
--- a/include/dm/root.h
+++ b/include/dm/root.h
@@ -19,7 +19,7 @@ extern struct list_head uclass_head;
  *
  * This function returns pointer to the root node of the driver tree,
  *
- * @return pointer to root device, or NULL if not inited yet
+ * Return: pointer to root device, or NULL if not inited yet
  */
 struct udevice *dm_root(void);
 
@@ -27,6 +27,8 @@ struct global_data;
 /**
  * dm_fixup_for_gd_move() - Handle global_data moving to a new place
  *
+ * @new_gd: Pointer to the new global data
+ *
  * The uclass list is part of global_data. Due to the way lists work, moving
  * the list will cause it to become invalid. This function fixes that up so
  * that the uclass list will work correctly.
@@ -40,7 +42,7 @@ void dm_fixup_for_gd_move(struct global_data *new_gd);
  *
  * @pre_reloc_only: If true, bind only drivers with the DM_FLAG_PRE_RELOC
  * flag. If false bind all drivers.
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dm_scan_plat(bool pre_reloc_only);
 
@@ -52,7 +54,7 @@ int dm_scan_plat(bool pre_reloc_only);
  *
  * @pre_reloc_only: If true, bind only nodes with special devicetree properties,
  * or drivers with the DM_FLAG_PRE_RELOC flag. If false bind all drivers.
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dm_scan_fdt(bool pre_reloc_only);
 
@@ -65,7 +67,7 @@ int dm_scan_fdt(bool pre_reloc_only);
  *
  * @pre_reloc_only: If true, bind only nodes with special devicetree properties,
  * or drivers with the DM_FLAG_PRE_RELOC flag. If false bind all drivers.
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dm_extended_scan(bool pre_reloc_only);
 
@@ -79,7 +81,7 @@ int dm_extended_scan(bool pre_reloc_only);
  *
  * @pre_reloc_only: If true, bind only nodes with special devicetree properties,
  * or drivers with the DM_FLAG_PRE_RELOC flag. If false bind all drivers.
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dm_scan_other(bool pre_reloc_only);
 
@@ -92,7 +94,7 @@ int dm_scan_other(bool pre_reloc_only);
  *
  * @pre_reloc_only: If true, bind only nodes with special devicetree properties,
  * or drivers with the DM_FLAG_PRE_RELOC flag. If false bind all drivers.
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dm_init_and_scan(bool pre_reloc_only);
 
@@ -103,7 +105,7 @@ int dm_init_and_scan(bool pre_reloc_only);
  * This needs to be called before anything uses the DM
  *
  * @of_live:	Enable live device tree
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dm_init(bool of_live);
 
@@ -111,7 +113,7 @@ int dm_init(bool of_live);
  * dm_uninit - Uninitialise Driver Model structures
  *
  * All devices will be removed and unbound
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dm_uninit(void);
 
@@ -124,7 +126,7 @@ int dm_uninit(void);
  * All devices with the matching flags set will be removed
  *
  * @flags: Flags for selective device removal
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dm_remove_devices_flags(uint flags);
 #else
-- 
2.25.1

[PATCH 3/9] doc: add include/dm/lists.h to the HTML documentation

[Patrick Delaunay]

Correct Sphinx style comments in include/dm/lists.h
and add the list API to the HTML documentation.

Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
---

 doc/api/dm.rst     | 1 +
 include/dm/lists.h | 8 +++++---
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/doc/api/dm.rst b/doc/api/dm.rst
index 181a454c24..168d129250 100644
--- a/doc/api/dm.rst
+++ b/doc/api/dm.rst
@@ -8,3 +8,4 @@ Uclass and Driver
 
 .. kernel-doc:: include/dm/uclass.h
 .. kernel-doc:: include/dm/root.h
+.. kernel-doc:: include/dm/lists.h
diff --git a/include/dm/lists.h b/include/dm/lists.h
index 5896ae3658..fc3b4ae585 100644
--- a/include/dm/lists.h
+++ b/include/dm/lists.h
@@ -19,13 +19,14 @@
  * for binding a driver given its name and plat.
  *
  * @name: Name of driver to look up
- * @return pointer to driver, or NULL if not found
+ * Return: pointer to driver, or NULL if not found
  */
 struct driver *lists_driver_lookup_name(const char *name);
 
 /**
  * lists_uclass_lookup() - Return uclass_driver based on ID of the class
- * id:		ID of the class
+ *
+ * @id:		ID of the class
  *
  * This function returns the pointer to uclass_driver, which is the class's
  * base structure based on the ID of the class. Returns NULL on error.
@@ -56,7 +57,8 @@ int lists_bind_drivers(struct udevice *parent, bool pre_reloc_only);
  * @drv: if non-NULL, force this driver to be bound
  * @pre_reloc_only: If true, bind only nodes with special devicetree properties,
  * or drivers with the DM_FLAG_PRE_RELOC flag. If false bind all drivers.
- * @return 0 if device was bound, -EINVAL if the device tree is invalid,
+ *
+ * Return: 0 if device was bound, -EINVAL if the device tree is invalid,
  * other -ve value on error
  */
 int lists_bind_fdt(struct udevice *parent, ofnode node, struct udevice **devp,
-- 
2.25.1

[PATCH 4/9] doc: add include/dm/platdata.h to the HTML documentation

[Patrick Delaunay]

Correct Sphinx style comments in include/dm/platdata.h
and add the associated API to the HTML documentation.

Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
---

 doc/api/dm.rst        | 1 +
 include/dm/platdata.h | 4 ++--
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/doc/api/dm.rst b/doc/api/dm.rst
index 168d129250..6f72b0b620 100644
--- a/doc/api/dm.rst
+++ b/doc/api/dm.rst
@@ -9,3 +9,4 @@ Uclass and Driver
 .. kernel-doc:: include/dm/uclass.h
 .. kernel-doc:: include/dm/root.h
 .. kernel-doc:: include/dm/lists.h
+.. kernel-doc:: include/dm/platdata.h
diff --git a/include/dm/platdata.h b/include/dm/platdata.h
index 4efb1dfe12..47ba8aab7a 100644
--- a/include/dm/platdata.h
+++ b/include/dm/platdata.h
@@ -40,7 +40,7 @@ struct driver_info {
 #endif
 
 /**
- * driver_rt - runtime information set up by U-Boot
+ * struct driver_rt - runtime information set up by U-Boot
  *
  * There is one of these for every driver_info in the linker list, indexed by
  * the driver_info idx value.
@@ -51,7 +51,7 @@ struct driver_rt {
 	struct udevice *dev;
 };
 
-/**
+/*
  * NOTE: Avoid using these except in extreme circumstances, where device tree
  * is not feasible (e.g. serial driver in SPL where <8KB of SRAM is
  * available). U-Boot's driver model uses device tree for configuration.
-- 
2.25.1

[PATCH 5/9] doc: add include/dm/device.h to the HTML documentation

[Patrick Delaunay]

Correct Sphinx style comments in include/dm/device.h
and add the driver model device API to the HTML documentation.

Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
---

 doc/api/dm.rst      |   5 ++
 include/dm/device.h | 209 ++++++++++++++++++++++++--------------------
 2 files changed, 121 insertions(+), 93 deletions(-)

diff --git a/doc/api/dm.rst b/doc/api/dm.rst
index 6f72b0b620..7a77a91c1f 100644
--- a/doc/api/dm.rst
+++ b/doc/api/dm.rst
@@ -10,3 +10,8 @@ Uclass and Driver
 .. kernel-doc:: include/dm/root.h
 .. kernel-doc:: include/dm/lists.h
 .. kernel-doc:: include/dm/platdata.h
+
+Device
+------
+
+.. kernel-doc:: include/dm/device.h
diff --git a/include/dm/device.h b/include/dm/device.h
index cf785f7ae2..bc8da72b50 100644
--- a/include/dm/device.h
+++ b/include/dm/device.h
@@ -145,7 +145,7 @@ enum {
  * @uclass_node: Used by uclass to link its devices
  * @child_head: List of children of this device
  * @sibling_node: Next device in list of all devices
- * @flags_: Flags for this device DM_FLAG_... (do not access outside driver
+ * @flags_: Flags for this device `DM_FLAG_...` (do not access outside driver
  *	model)
  * @seq_: Allocated sequence number for this device (-1 = none). This is set up
  * when the device is bound and is unique within the device's uclass. If the
@@ -193,14 +193,14 @@ struct udevice {
 };
 
 /**
- * udevice_rt - runtime information set up by U-Boot
+ * struct udevice_rt - runtime information set up by U-Boot
  *
  * This is only used with OF_PLATDATA_RT
  *
  * There is one of these for every udevice in the linker list, indexed by
  * the udevice_info idx value.
  *
- * @flags_: Flags for this device DM_FLAG_... (do not access outside driver
+ * @flags_: Flags for this device `DM_FLAG_...` (do not access outside driver
  *	model)
  */
 struct udevice_rt {
@@ -239,7 +239,7 @@ static inline void dev_bic_flags(struct udevice *dev, u32 bic)
  * dev_ofnode() - get the DT node reference associated with a udevice
  *
  * @dev:	device to check
- * @return reference of the the device's DT node
+ * Return: reference of the device's DT node
  */
 static inline ofnode dev_ofnode(const struct udevice *dev)
 {
@@ -351,7 +351,7 @@ struct udevice_id {
  * @ops: Driver-specific operations. This is typically a list of function
  * pointers defined by the driver, to implement driver functions required by
  * the uclass.
- * @flags: driver flags - see DM_FLAGS_...
+ * @flags: driver flags - see `DM_FLAGS_...`
  * @acpi_ops: Advanced Configuration and Power Interface (ACPI) operations,
  * allowing the device to add things to the ACPI tables passed to Linux
  */
@@ -378,11 +378,24 @@ struct driver {
 #endif
 };
 
-/* Declare a new U-Boot driver */
+/**
+ * U_BOOT_DRIVER() - Declare a new U-Boot driver
+ * @__name: name of the driver
+ */
 #define U_BOOT_DRIVER(__name)						\
 	ll_entry_declare(struct driver, __name, driver)
 
-/* Get a pointer to a given driver */
+/**
+ * DM_DRIVER_GET() - Get a pointer to a given driver
+ *
+ * This is useful in code for referencing a driver at build time.
+ * Before this is used, an extern U_BOOT_DRIVER() must have been
+ * declared.
+ *
+ * @__name:	Name of the driver. This must be a valid C identifier,
+ * used by the linker_list
+ * Return: struct driver * for the driver
+ */
 #define DM_DRIVER_GET(__name)						\
 	ll_entry_get(struct driver, __name, driver)
 
@@ -392,60 +405,69 @@ struct driver {
  * This is useful in data structures and code for referencing a driver at
  * build time. Before this is used, an extern U_BOOT_DRIVER() must have been
  * declared.
+ * This is like DM_DRIVER_GET, but without the extra code, so it is suitable
+ * for putting into data structures.
  *
- * For example:
- *
- * extern U_BOOT_DRIVER(sandbox_fixed_clock);
+ * For example: ::
  *
- * struct driver *drvs[] = {
- *	DM_DRIVER_REF(sandbox_fixed_clock),
- * };
+ *   extern U_BOOT_DRIVER(sandbox_fixed_clock);
+ *   struct driver *drvs[] = {
+ *       DM_DRIVER_REF(sandbox_fixed_clock),
+ *   };
  *
- * @_name: Name of the driver. This must be a valid C identifier, used by the
- *	linker_list
- * @returns struct driver * for the driver
+ * @_name:	Name of the driver. This must be a valid C identifier,
+ * used by the linker_list
+ * Return: struct driver * for the driver
  */
 #define DM_DRIVER_REF(_name)					\
 	ll_entry_ref(struct driver, _name, driver)
 
 /**
- * Declare a macro to state a alias for a driver name. This macro will
- * produce no code but its information will be parsed by tools like
- * dtoc
+ * DM_DRIVER_ALIAS() - Declare a macro to state a alias for a driver name
+ *
+ * This macro will produce no code but its information will be parsed by tools
+ * like dtoc
+ *
+ * @__name:	name of driver
+ * @__alias:	alias for the driver name
  */
 #define DM_DRIVER_ALIAS(__name, __alias)
 
 /**
- * Declare a macro to indicate which phase of U-Boot this driver is fore.
- *
+ * DM_PHASE() - Declare a macro to indicate which phase of U-Boot this driver is fore.
  *
  * This macro produces no code but its information will be parsed by dtoc. The
  * macro can be only be used once in a driver. Put it within the U_BOOT_DRIVER()
- * declaration, e.g.:
+ * declaration, e.g.: ::
+ *
+ *   U_BOOT_DRIVER(cpu) = {
+ *       .name = ...
+ *       ...
+ *       DM_PHASE(tpl)
+ *   };
  *
- * U_BOOT_DRIVER(cpu) = {
- *	.name = ...
- *	...
- *	DM_PHASE(tpl)
- * };
+ * @_phase:	Associated phase of U-Boot ("spl", "tpl")
  */
 #define DM_PHASE(_phase)
 
 /**
- * Declare a macro to declare a header needed for a driver. Often the correct
- * header can be found automatically, but only for struct declarations. For
- * enums and #defines used in the driver declaration and declared in a different
- * header from the structs, this macro must be used.
+ * DM_HEADER() - Declare a macro to declare a header needed for a driver.
+ *
+ * Often the correct header can be found automatically, but only for struct
+ * declarations. For enums and #defines used in the driver declaration and
+ * declared in a different header from the structs, this macro must be used.
  *
  * This macro produces no code but its information will be parsed by dtoc. The
  * macro can be used multiple times with different headers, for the same driver.
- * Put it within the U_BOOT_DRIVER() declaration, e.g.:
+ * Put it within the U_BOOT_DRIVER() declaration, e.g.: ::
+ *
+ *   U_BOOT_DRIVER(cpu) = {
+ *       .name = ...
+ *       ...
+ *       DM_HEADER(<asm/cpu.h>)
+ *   };
  *
- * U_BOOT_DRIVER(cpu) = {
- *	.name = ...
- *	...
- *	DM_HEADER(<asm/cpu.h>)
- * };
+ * @_hdr:	header needed for a driver
  */
 #define DM_HEADER(_hdr)
 
@@ -454,8 +476,8 @@ struct driver {
  *
  * This checks that dev is not NULL, but no other checks for now
  *
- * @dev		Device to check
- * @return platform data, or NULL if none
+ * @dev:	Device to check
+ * Return: platform data, or NULL if none
  */
 void *dev_get_plat(const struct udevice *dev);
 
@@ -464,8 +486,8 @@ void *dev_get_plat(const struct udevice *dev);
  *
  * This checks that dev is not NULL, but no other checks for now
  *
- * @dev		Device to check
- * @return parent's platform data, or NULL if none
+ * @dev:	Device to check
+ * Return: parent's platform data, or NULL if none
  */
 void *dev_get_parent_plat(const struct udevice *dev);
 
@@ -474,8 +496,8 @@ void *dev_get_parent_plat(const struct udevice *dev);
  *
  * This checks that dev is not NULL, but no other checks for now
  *
- * @dev		Device to check
- * @return uclass's platform data, or NULL if none
+ * @dev:	Device to check
+ * Return: uclass's platform data, or NULL if none
  */
 void *dev_get_uclass_plat(const struct udevice *dev);
 
@@ -484,8 +506,8 @@ void *dev_get_uclass_plat(const struct udevice *dev);
  *
  * This checks that dev is not NULL, but no other checks for now
  *
- * @dev		Device to check
- * @return private data, or NULL if none
+ * @dev:	Device to check
+ * Return: private data, or NULL if none
  */
 void *dev_get_priv(const struct udevice *dev);
 
@@ -498,8 +520,8 @@ void *dev_get_priv(const struct udevice *dev);
  *
  * This checks that dev is not NULL, but no other checks for now
  *
- * @dev		Device to check
- * @return parent data, or NULL if none
+ * @dev:	Device to check
+ * Return: parent data, or NULL if none
  */
 void *dev_get_parent_priv(const struct udevice *dev);
 
@@ -508,16 +530,16 @@ void *dev_get_parent_priv(const struct udevice *dev);
  *
  * This checks that dev is not NULL, but no other checks for now
  *
- * @dev		Device to check
- * @return private uclass data for this device, or NULL if none
+ * @dev:	Device to check
+ * Return: private uclass data for this device, or NULL if none
  */
 void *dev_get_uclass_priv(const struct udevice *dev);
 
 /**
- * struct dev_get_parent() - Get the parent of a device
+ * dev_get_parent() - Get the parent of a device
  *
  * @child:	Child to check
- * @return parent of child, or NULL if this is the root device
+ * Return: parent of child, or NULL if this is the root device
  */
 struct udevice *dev_get_parent(const struct udevice *child);
 
@@ -529,13 +551,14 @@ struct udevice *dev_get_parent(const struct udevice *child);
  * returns the associated data value for that compatible string. This is
  * the 'data' field in struct udevice_id.
  *
- * As an example, consider this structure:
- * static const struct udevice_id tegra_i2c_ids[] = {
- *	{ .compatible = "nvidia,tegra114-i2c", .data = TYPE_114 },
- *	{ .compatible = "nvidia,tegra20-i2c", .data = TYPE_STD },
- *	{ .compatible = "nvidia,tegra20-i2c-dvc", .data = TYPE_DVC },
- *	{ }
- * };
+ * As an example, consider this structure: ::
+ *
+ *  static const struct udevice_id tegra_i2c_ids[] = {
+ *      { .compatible = "nvidia,tegra114-i2c", .data = TYPE_114 },
+ *      { .compatible = "nvidia,tegra20-i2c", .data = TYPE_STD },
+ *      { .compatible = "nvidia,tegra20-i2c-dvc", .data = TYPE_DVC },
+ *      { }
+ *  };
  *
  * When driver model finds a driver for this it will store the 'data' value
  * corresponding to the compatible string it matches. This function returns
@@ -544,7 +567,7 @@ struct udevice *dev_get_parent(const struct udevice *child);
  * For USB devices, this is the driver_info field in struct usb_device_id.
  *
  * @dev:	Device to check
- * @return driver data (0 if none is provided)
+ * Return: driver data (0 if none is provided)
  */
 ulong dev_get_driver_data(const struct udevice *dev);
 
@@ -555,7 +578,7 @@ ulong dev_get_driver_data(const struct udevice *dev);
  * driver's operations.
  *
  * @dev:	Device to check
- * @return void pointer to driver's operations or NULL for NULL-dev or NULL-ops
+ * Return: void pointer to driver's operations or NULL for NULL-dev or NULL-ops
  */
 const void *dev_get_driver_ops(const struct udevice *dev);
 
@@ -563,7 +586,7 @@ const void *dev_get_driver_ops(const struct udevice *dev);
  * device_get_uclass_id() - return the uclass ID of a device
  *
  * @dev:	Device to check
- * @return uclass ID for the device
+ * Return: uclass ID for the device
  */
 enum uclass_id device_get_uclass_id(const struct udevice *dev);
 
@@ -573,7 +596,7 @@ enum uclass_id device_get_uclass_id(const struct udevice *dev);
  * This checks that dev is not NULL.
  *
  * @dev:	Device to check
- * @return  pointer to the uclass name for the device
+ * Return:  pointer to the uclass name for the device
  */
 const char *dev_get_uclass_name(const struct udevice *dev);
 
@@ -583,11 +606,11 @@ const char *dev_get_uclass_name(const struct udevice *dev);
  * Returns the numbered child, 0 being the first. This does not use
  * sequence numbers, only the natural order.
  *
- * @dev:	Parent device to check
+ * @parent:	Parent device to check
  * @index:	Child index
  * @devp:	Returns pointer to device
- * @return 0 if OK, -ENODEV if no such device, other error if the device fails
- *	   to probe
+ * Return:
+ * 0 if OK, -ENODEV if no such device, other error if the device fails to probe
  */
 int device_get_child(const struct udevice *parent, int index,
 		     struct udevice **devp);
@@ -619,7 +642,7 @@ int device_get_decendent_count(const struct udevice *parent);
  * @seq: Sequence number to find (0=first)
  * @devp: Returns pointer to device (there is only one per for each seq).
  * Set to NULL if none is found
- * @return 0 if OK, -ENODEV if not found
+ * Return: 0 if OK, -ENODEV if not found
  */
 int device_find_child_by_seq(const struct udevice *parent, int seq,
 			     struct udevice **devp);
@@ -637,7 +660,7 @@ int device_find_child_by_seq(const struct udevice *parent, int seq,
  * @seq: Sequence number to find (0=first)
  * @devp: Returns pointer to device (there is only one per for each seq)
  * Set to NULL if none is found
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int device_get_child_by_seq(const struct udevice *parent, int seq,
 			    struct udevice **devp);
@@ -650,7 +673,7 @@ int device_get_child_by_seq(const struct udevice *parent, int seq,
  * @parent: Parent device
  * @of_offset: Device tree offset to find
  * @devp: Returns pointer to device if found, otherwise this is set to NULL
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int device_find_child_by_of_offset(const struct udevice *parent, int of_offset,
 				   struct udevice **devp);
@@ -665,7 +688,7 @@ int device_find_child_by_of_offset(const struct udevice *parent, int of_offset,
  * @parent: Parent device
  * @of_offset: Device tree offset to find
  * @devp: Returns pointer to device if found, otherwise this is set to NULL
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int device_get_child_by_of_offset(const struct udevice *parent, int of_offset,
 				  struct udevice **devp);
@@ -680,7 +703,7 @@ int device_get_child_by_of_offset(const struct udevice *parent, int of_offset,
  *
  * @node: Device tree ofnode to find
  * @devp: Returns pointer to device if found, otherwise this is set to NULL
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 
 int device_find_global_by_ofnode(ofnode node, struct udevice **devp);
@@ -695,7 +718,7 @@ int device_find_global_by_ofnode(ofnode node, struct udevice **devp);
  *
  * @node: Device tree ofnode to find
  * @devp: Returns pointer to device if found, otherwise this is set to NULL
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int device_get_global_by_ofnode(ofnode node, struct udevice **devp);
 
@@ -715,7 +738,7 @@ int device_get_global_by_ofnode(ofnode node, struct udevice **devp);
  *
  * @idx: Index number of the driver_info/udevice structure (0=first)
  * @devp: Returns pointer to device if found, otherwise this is set to NULL
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int device_get_by_ofplat_idx(uint idx, struct udevice **devp);
 
@@ -724,7 +747,7 @@ int device_get_by_ofplat_idx(uint idx, struct udevice **devp);
  *
  * @parent: Parent device to search
  * @devp: Returns first child device, or NULL if none
- * @return 0
+ * Return: 0
  */
 int device_find_first_child(const struct udevice *parent,
 			    struct udevice **devp);
@@ -734,7 +757,7 @@ int device_find_first_child(const struct udevice *parent,
  *
  * @devp: Pointer to previous child device on entry. Returns pointer to next
  *		child device, or NULL if none
- * @return 0
+ * Return: 0
  */
 int device_find_next_child(struct udevice **devp);
 
@@ -749,7 +772,7 @@ int device_find_next_child(struct udevice **devp);
  * @parent:	Parent device to search
  * @uclass_id:	Uclass to look for
  * @devp:	Returns device found, if any, else NULL
- * @return 0 if found, else -ENODEV
+ * Return: 0 if found, else -ENODEV
  */
 int device_find_first_inactive_child(const struct udevice *parent,
 				     enum uclass_id uclass_id,
@@ -761,7 +784,7 @@ int device_find_first_inactive_child(const struct udevice *parent,
  * @parent: Parent device to search
  * @uclass_id:	Uclass to look for
  * @devp: Returns first child device in that uclass, if any, else NULL
- * @return 0 if found, else -ENODEV
+ * Return: 0 if found, else -ENODEV
  */
 int device_find_first_child_by_uclass(const struct udevice *parent,
 				      enum uclass_id uclass_id,
@@ -774,7 +797,7 @@ int device_find_first_child_by_uclass(const struct udevice *parent,
  * @name:	Name to look for
  * @len:	Length of the name
  * @devp:	Returns device found, if any
- * @return 0 if found, else -ENODEV
+ * Return: 0 if found, else -ENODEV
  */
 int device_find_child_by_namelen(const struct udevice *parent, const char *name,
 				 int len, struct udevice **devp);
@@ -785,7 +808,7 @@ int device_find_child_by_namelen(const struct udevice *parent, const char *name,
  * @parent:	Parent device to search
  * @name:	Name to look for
  * @devp:	Returns device found, if any
- * @return 0 if found, else -ENODEV
+ * Return: 0 if found, else -ENODEV
  */
 int device_find_child_by_name(const struct udevice *parent, const char *name,
 			      struct udevice **devp);
@@ -798,7 +821,7 @@ int device_find_child_by_name(const struct udevice *parent, const char *name,
  *
  * @parent: Parent to check
  * @devp: Returns child that was found, if any
- * @return 0 on success, -ENODEV if no children, other -ve on error
+ * Return: 0 on success, -ENODEV if no children, other -ve on error
  */
 int device_first_child_ofdata_err(struct udevice *parent,
 				  struct udevice **devp);
@@ -811,7 +834,7 @@ int device_first_child_ofdata_err(struct udevice *parent,
  *
  * @devp: On entry, points to the previous child; on exit returns the child that
  *	was found, if any
- * @return 0 on success, -ENODEV if no children, other -ve on error
+ * Return: 0 on success, -ENODEV if no children, other -ve on error
  */
 int device_next_child_ofdata_err(struct udevice **devp);
 
@@ -822,7 +845,7 @@ int device_next_child_ofdata_err(struct udevice **devp);
  *
  * @parent:	Parent device to search
  * @devp:	Returns device found, if any
- * @return 0 if found, -ENODEV if not, -ve error if device failed to probe
+ * Return: 0 if found, -ENODEV if not, -ve error if device failed to probe
  */
 int device_first_child_err(struct udevice *parent, struct udevice **devp);
 
@@ -833,7 +856,7 @@ int device_first_child_err(struct udevice *parent, struct udevice **devp);
  *
  * @devp: On entry, pointer to device to lookup. On exit, returns pointer
  * to the next sibling if no error occurred
- * @return 0 if found, -ENODEV if not, -ve error if device failed to probe
+ * Return: 0 if found, -ENODEV if not, -ve error if device failed to probe
  */
 int device_next_child_err(struct udevice **devp);
 
@@ -841,7 +864,7 @@ int device_next_child_err(struct udevice **devp);
  * device_has_children() - check if a device has any children
  *
  * @dev:	Device to check
- * @return true if the device has one or more children
+ * Return: true if the device has one or more children
  */
 bool device_has_children(const struct udevice *dev);
 
@@ -849,7 +872,7 @@ bool device_has_children(const struct udevice *dev);
  * device_has_active_children() - check if a device has any active children
  *
  * @dev:	Device to check
- * @return true if the device has one or more children and at least one of
+ * Return: true if the device has one or more children and at least one of
  * them is active (probed).
  */
 bool device_has_active_children(const struct udevice *dev);
@@ -862,7 +885,7 @@ bool device_has_active_children(const struct udevice *dev);
  * view of devices is being displayed.
  *
  * @dev:	Device to check
- * @return true if there are no more siblings after this one - i.e. is it
+ * Return: true if there are no more siblings after this one - i.e. is it
  * last in the list.
  */
 bool device_is_last_sibling(const struct udevice *dev);
@@ -880,7 +903,7 @@ bool device_is_last_sibling(const struct udevice *dev);
  * @dev:	Device to update
  * @name:	New name (this string is allocated new memory and attached to
  *		the device)
- * @return 0 if OK, -ENOMEM if there is not enough memory to allocate the
+ * Return: 0 if OK, -ENOMEM if there is not enough memory to allocate the
  * string
  */
 int device_set_name(struct udevice *dev, const char *name);
@@ -903,7 +926,7 @@ void device_set_name_alloced(struct udevice *dev);
  * @dev:	udevice pointer for which compatible needs to be verified.
  * @compat:	Compatible string which needs to verified in the given
  *		device
- * @return true if OK, false if the compatible is not found
+ * Return: true if OK, false if the compatible is not found
  */
 bool device_is_compatible(const struct udevice *dev, const char *compat);
 
@@ -914,7 +937,7 @@ bool device_is_compatible(const struct udevice *dev, const char *compat);
  * This allows to check whether the machine is comaptible with the compat.
  *
  * @compat:	Compatible string which needs to verified
- * @return true if OK, false if the compatible is not found
+ * Return: true if OK, false if the compatible is not found
  */
 bool of_machine_is_compatible(const char *compat);
 
@@ -922,7 +945,7 @@ bool of_machine_is_compatible(const char *compat);
  * dev_disable_by_path() - Disable a device given its device tree path
  *
  * @path:	The device tree path identifying the device to be disabled
- * @return 0 on success, -ve on error
+ * Return: 0 on success, -ve on error
  */
 int dev_disable_by_path(const char *path);
 
@@ -930,7 +953,7 @@ int dev_disable_by_path(const char *path);
  * dev_enable_by_path() - Enable a device given its device tree path
  *
  * @path:	The device tree path identifying the device to be enabled
- * @return 0 on success, -ve on error
+ * Return: 0 on success, -ve on error
  */
 int dev_enable_by_path(const char *path);
 
@@ -938,7 +961,7 @@ int dev_enable_by_path(const char *path);
  * device_is_on_pci_bus - Test if a device is on a PCI bus
  *
  * @dev:	device to test
- * @return:	true if it is on a PCI bus, false otherwise
+ * Return:	true if it is on a PCI bus, false otherwise
  */
 static inline bool device_is_on_pci_bus(const struct udevice *dev)
 {
@@ -971,7 +994,7 @@ static inline bool device_is_on_pci_bus(const struct udevice *dev)
  *
  * This stops when it gets an error, with @pos set to the device that failed to
  * read ofdata.
-
+ *
  * This creates a for() loop which works through the available children of
  * a device in order from start to end. Device ofdata is read by calling
  * device_of_to_plat() on each one. The devices are not probed.
@@ -1012,7 +1035,7 @@ static inline bool device_is_on_pci_bus(const struct udevice *dev)
  * be bound.
  *
  * @dev:	Device to scan
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dm_scan_fdt_dev(struct udevice *dev);
 
-- 
2.25.1

[PATCH 6/9] doc: add include/dm/devres.h to the HTML documentation

[Patrick Delaunay]

Correct Sphinx style comments in include/dm/devres.h
and add the driver model device resource API, devres_*(),
to the HTML documentation.

Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
---

 doc/api/dm.rst      |  1 +
 include/dm/devres.h | 14 +++++++-------
 2 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/doc/api/dm.rst b/doc/api/dm.rst
index 7a77a91c1f..0342620786 100644
--- a/doc/api/dm.rst
+++ b/doc/api/dm.rst
@@ -15,3 +15,4 @@ Device
 ------
 
 .. kernel-doc:: include/dm/device.h
+.. kernel-doc:: include/dm/devres.h
diff --git a/include/dm/devres.h b/include/dm/devres.h
index 17bb1ee8da..0ab277ec38 100644
--- a/include/dm/devres.h
+++ b/include/dm/devres.h
@@ -51,7 +51,7 @@ void *_devres_alloc(dr_release_t release, size_t size, gfp_t gfp);
  * with @release.  The returned pointer can be passed to
  * other devres_*() functions.
  *
- * RETURNS:
+ * Return:
  * Pointer to allocated devres on success, NULL on failure.
  */
 #define devres_alloc(release, size, gfp) \
@@ -87,7 +87,7 @@ void devres_add(struct udevice *dev, void *res);
  * and for which @match returns 1.  If @match is NULL, it's considered
  * to match all.
  *
- * @return pointer to found devres, NULL if not found.
+ * Return: pointer to found devres, NULL if not found.
  */
 void *devres_find(struct udevice *dev, dr_release_t release,
 		  dr_match_t match, void *match_data);
@@ -103,7 +103,7 @@ void *devres_find(struct udevice *dev, dr_release_t release,
  * as @new_res and for which @match return 1.  If found, @new_res is
  * freed; otherwise, @new_res is added atomically.
  *
- * @return ointer to found or added devres.
+ * Return: pointer to found or added devres.
  */
 void *devres_get(struct udevice *dev, void *new_res,
 		 dr_match_t match, void *match_data);
@@ -120,7 +120,7 @@ void *devres_get(struct udevice *dev, void *new_res,
  * match all.  If found, the resource is removed atomically and
  * returned.
  *
- * @return ointer to removed devres on success, NULL if not found.
+ * Return: pointer to removed devres on success, NULL if not found.
  */
 void *devres_remove(struct udevice *dev, dr_release_t release,
 		    dr_match_t match, void *match_data);
@@ -140,7 +140,7 @@ void *devres_remove(struct udevice *dev, dr_release_t release,
  * only the devres-allocated data will be freed.  The caller becomes
  * responsible for freeing any other data.
  *
- * @return 0 if devres is found and freed, -ENOENT if not found.
+ * Return: 0 if devres is found and freed, -ENOENT if not found.
  */
 int devres_destroy(struct udevice *dev, dr_release_t release,
 		   dr_match_t match, void *match_data);
@@ -157,7 +157,7 @@ int devres_destroy(struct udevice *dev, dr_release_t release,
  * match all.  If found, the resource is removed atomically, the
  * release function called and the resource freed.
  *
- * @return 0 if devres is found and freed, -ENOENT if not found.
+ * Return: 0 if devres is found and freed, -ENOENT if not found.
  */
 int devres_release(struct udevice *dev, dr_release_t release,
 		   dr_match_t match, void *match_data);
@@ -173,7 +173,7 @@ int devres_release(struct udevice *dev, dr_release_t release,
  * automatically freed on driver detach.  Like all other devres
  * resources, guaranteed alignment is unsigned long long.
  *
- * @return pointer to allocated memory on success, NULL on failure.
+ * Return: pointer to allocated memory on success, NULL on failure.
  */
 void *devm_kmalloc(struct udevice *dev, size_t size, gfp_t gfp);
 static inline void *devm_kzalloc(struct udevice *dev, size_t size, gfp_t gfp)
-- 
2.25.1

[PATCH 7/9] doc: add include/dm/read.h to the HTML documentation

[Patrick Delaunay]

Correct Sphinx style comments in include/dm/read.h
and add the device read from device tree API to the HTML
documentation.

Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
---

 doc/api/dm.rst    |   1 +
 include/dm/read.h | 163 +++++++++++++++++++++++-----------------------
 2 files changed, 82 insertions(+), 82 deletions(-)

diff --git a/doc/api/dm.rst b/doc/api/dm.rst
index 0342620786..19a473f1f0 100644
--- a/doc/api/dm.rst
+++ b/doc/api/dm.rst
@@ -16,3 +16,4 @@ Device
 
 .. kernel-doc:: include/dm/device.h
 .. kernel-doc:: include/dm/devres.h
+.. kernel-doc:: include/dm/read.h
diff --git a/include/dm/read.h b/include/dm/read.h
index 75c6ad6ee4..18b84905f4 100644
--- a/include/dm/read.h
+++ b/include/dm/read.h
@@ -37,7 +37,7 @@ static inline const struct device_node *dev_np(const struct udevice *dev)
  * @dev:	device to read DT property from
  * @propname:	name of the property to read from
  * @outp:	place to put value (if found)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dev_read_u32(const struct udevice *dev, const char *propname, u32 *outp);
 
@@ -47,7 +47,7 @@ int dev_read_u32(const struct udevice *dev, const char *propname, u32 *outp);
  * @dev:	device to read DT property from
  * @propname:	name of the property to read from
  * @def:	default value to return if the property has no value
- * @return property value, or @def if not found
+ * Return: property value, or @def if not found
  */
 int dev_read_u32_default(const struct udevice *dev, const char *propname,
 			 int def);
@@ -60,7 +60,7 @@ int dev_read_u32_default(const struct udevice *dev, const char *propname,
  * @propname:	name of the property to read from
  * @index:	index of the integer to return
  * @outp:	place to put value (if found)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dev_read_u32_index(struct udevice *dev, const char *propname, int index,
 		       u32 *outp);
@@ -73,7 +73,7 @@ int dev_read_u32_index(struct udevice *dev, const char *propname, int index,
  * @propname:	name of the property to read from
  * @index:	index of the integer to return
  * @def:	default value to return if the property has no value
- * @return property value, or @def if not found
+ * Return: property value, or @def if not found
  */
 u32 dev_read_u32_index_default(struct udevice *dev, const char *propname,
 			       int index, u32 def);
@@ -84,7 +84,7 @@ u32 dev_read_u32_index_default(struct udevice *dev, const char *propname,
  * @dev:	device to read DT property from
  * @propname:	name of the property to read from
  * @outp:	place to put value (if found)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dev_read_s32(const struct udevice *dev, const char *propname, s32 *outp);
 
@@ -94,7 +94,7 @@ int dev_read_s32(const struct udevice *dev, const char *propname, s32 *outp);
  * @dev:	device to read DT property from
  * @propname:	name of the property to read from
  * @def:	default value to return if the property has no value
- * @return property value, or @def if not found
+ * Return: property value, or @def if not found
  */
 int dev_read_s32_default(const struct udevice *dev, const char *propname,
 			 int def);
@@ -107,7 +107,7 @@ int dev_read_s32_default(const struct udevice *dev, const char *propname,
  * @dev:	device to read DT property from
  * @propname:	name of the property to read from
  * @outp:	place to put value (if found)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dev_read_u32u(const struct udevice *dev, const char *propname, uint *outp);
 
@@ -117,7 +117,7 @@ int dev_read_u32u(const struct udevice *dev, const char *propname, uint *outp);
  * @dev:        device to read DT property from
  * @propname:   name of the property to read from
  * @outp:       place to put value (if found)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dev_read_u64(const struct udevice *dev, const char *propname, u64 *outp);
 
@@ -127,7 +127,7 @@ int dev_read_u64(const struct udevice *dev, const char *propname, u64 *outp);
  * @dev:        device to read DT property from
  * @propname:   name of the property to read from
  * @def:        default value to return if the property has no value
- * @return property value, or @def if not found
+ * Return: property value, or @def if not found
  */
 u64 dev_read_u64_default(const struct udevice *dev, const char *propname,
 			 u64 def);
@@ -137,7 +137,7 @@ u64 dev_read_u64_default(const struct udevice *dev, const char *propname,
  *
  * @dev:	device to read DT property from
  * @propname:	name of the property to read
- * @return string from property value, or NULL if there is no such property
+ * Return: string from property value, or NULL if there is no such property
  */
 const char *dev_read_string(const struct udevice *dev, const char *propname);
 
@@ -146,7 +146,7 @@ const char *dev_read_string(const struct udevice *dev, const char *propname);
  *
  * @dev:	device to read DT property from
  * @propname:	name of property to read
- * @return true if property is present (meaning true), false if not present
+ * Return: true if property is present (meaning true), false if not present
  */
 bool dev_read_bool(const struct udevice *dev, const char *propname);
 
@@ -155,17 +155,17 @@ bool dev_read_bool(const struct udevice *dev, const char *propname);
  *
  * @dev:	device whose DT node contains the subnode
  * @subnode_name: name of subnode to find
- * @return reference to subnode (which can be invalid if there is no such
+ * Return: reference to subnode (which can be invalid if there is no such
  * subnode)
  */
-ofnode dev_read_subnode(const struct udevice *dev, const char *subbnode_name);
+ofnode dev_read_subnode(const struct udevice *dev, const char *subnode_name);
 
 /**
  * dev_read_size() - read the size of a property
  *
  * @dev: device to check
  * @propname: property to check
- * @return size of property if present, or -EINVAL if not
+ * Return: size of property if present, or -EINVAL if not
  */
 int dev_read_size(const struct udevice *dev, const char *propname);
 
@@ -176,7 +176,7 @@ int dev_read_size(const struct udevice *dev, const char *propname);
  * @index: the 'reg' property can hold a list of <addr, size> pairs
  *	   and @index is used to select which one is required
  *
- * @return address or FDT_ADDR_T_NONE if not found
+ * Return: address or FDT_ADDR_T_NONE if not found
  */
 fdt_addr_t dev_read_addr_index(const struct udevice *dev, int index);
 
@@ -188,7 +188,7 @@ fdt_addr_t dev_read_addr_index(const struct udevice *dev, int index);
  * @index: the 'reg' property can hold a list of <addr, size> pairs
  *	   and @index is used to select which one is required
  *
- * @return pointer or NULL if not found
+ * Return: pointer or NULL if not found
  */
 void *dev_read_addr_index_ptr(const struct udevice *dev, int index);
 
@@ -200,7 +200,7 @@ void *dev_read_addr_index_ptr(const struct udevice *dev, int index);
  *	   and @index is used to select which one is required
  * @size: place to put size value (on success)
  *
- * @return address or FDT_ADDR_T_NONE if not found
+ * Return: address or FDT_ADDR_T_NONE if not found
  */
 fdt_addr_t dev_read_addr_size_index(const struct udevice *dev, int index,
 				    fdt_size_t *size);
@@ -213,7 +213,7 @@ fdt_addr_t dev_read_addr_size_index(const struct udevice *dev, int index,
  * @index: the 'reg' property can hold a list of <addr, size> pairs
  *	   and @index is used to select which one is required
  *
- * @return pointer or NULL if not found
+ * Return: pointer or NULL if not found
  */
 void *dev_remap_addr_index(const struct udevice *dev, int index);
 
@@ -225,7 +225,7 @@ void *dev_remap_addr_index(const struct udevice *dev, int index);
  *	  'reg-names' property providing named-based identification. @index
  *	  indicates the value to search for in 'reg-names'.
  *
- * @return address or FDT_ADDR_T_NONE if not found
+ * Return: address or FDT_ADDR_T_NONE if not found
  */
 fdt_addr_t dev_read_addr_name(const struct udevice *dev, const char *name);
 
@@ -238,7 +238,7 @@ fdt_addr_t dev_read_addr_name(const struct udevice *dev, const char *name);
  *	  indicates the value to search for in 'reg-names'.
  *  @size: place to put size value (on success)
  *
- * @return address or FDT_ADDR_T_NONE if not found
+ * Return: address or FDT_ADDR_T_NONE if not found
  */
 fdt_addr_t dev_read_addr_size_name(const struct udevice *dev, const char *name,
 				   fdt_size_t *size);
@@ -252,7 +252,7 @@ fdt_addr_t dev_read_addr_size_name(const struct udevice *dev, const char *name,
  *	  'reg-names' property providing named-based identification. @index
  *	  indicates the value to search for in 'reg-names'.
  *
- * @return pointer or NULL if not found
+ * Return: pointer or NULL if not found
  */
 void *dev_remap_addr_name(const struct udevice *dev, const char *name);
 
@@ -261,7 +261,7 @@ void *dev_remap_addr_name(const struct udevice *dev, const char *name);
  *
  * @dev: Device to read from
  *
- * @return address or FDT_ADDR_T_NONE if not found
+ * Return: address or FDT_ADDR_T_NONE if not found
  */
 fdt_addr_t dev_read_addr(const struct udevice *dev);
 
@@ -271,7 +271,7 @@ fdt_addr_t dev_read_addr(const struct udevice *dev);
  *
  * @dev: Device to read from
  *
- * @return pointer or NULL if not found
+ * Return: pointer or NULL if not found
  */
 void *dev_read_addr_ptr(const struct udevice *dev);
 
@@ -291,7 +291,7 @@ void *dev_read_addr_ptr(const struct udevice *dev);
  *    fdtdec_get_addr() and friends.
  *
  * @dev: Device to read from
- * @return address or FDT_ADDR_T_NONE if not found
+ * Return: address or FDT_ADDR_T_NONE if not found
  */
 fdt_addr_t dev_read_addr_pci(const struct udevice *dev);
 
@@ -301,7 +301,7 @@ fdt_addr_t dev_read_addr_pci(const struct udevice *dev);
  *
  * @dev: Device to read from
  *
- * @return pointer or NULL if not found
+ * Return: pointer or NULL if not found
  */
 void *dev_remap_addr(const struct udevice *dev);
 
@@ -314,7 +314,7 @@ void *dev_remap_addr(const struct udevice *dev);
  * @dev: Device to read from
  * @propname: property to read
  * @sizep: place to put size value (on success)
- * @return address value, or FDT_ADDR_T_NONE on error
+ * Return: address value, or FDT_ADDR_T_NONE on error
  */
 fdt_addr_t dev_read_addr_size(const struct udevice *dev, const char *propname,
 			      fdt_size_t *sizep);
@@ -323,7 +323,7 @@ fdt_addr_t dev_read_addr_size(const struct udevice *dev, const char *propname,
  * dev_read_name() - get the name of a device's node
  *
  * @dev: Device to read from
- * @return name of node
+ * Return: name of node
  */
 const char *dev_read_name(const struct udevice *dev);
 
@@ -340,12 +340,12 @@ const char *dev_read_name(const struct udevice *dev);
  * @propname: name of the property containing the string list
  * @string: string to look up in the string list
  *
- * @return:
+ * Return:
  *   the index of the string in the list of strings
  *   -ENODATA if the property is not found
  *   -EINVAL on some other error
  */
-int dev_read_stringlist_search(const struct udevice *dev, const char *property,
+int dev_read_stringlist_search(const struct udevice *dev, const char *propname,
 			       const char *string);
 
 /**
@@ -354,9 +354,9 @@ int dev_read_stringlist_search(const struct udevice *dev, const char *property,
  * @dev: device to examine
  * @propname: name of the property containing the string list
  * @index: index of the string to return
- * @out: return location for the string
+ * @outp: return location for the string
  *
- * @return:
+ * Return:
  *   length of string, if found or -ve error value if not found
  */
 int dev_read_string_index(const struct udevice *dev, const char *propname,
@@ -367,7 +367,7 @@ int dev_read_string_index(const struct udevice *dev, const char *propname,
  *
  * @dev: device to examine
  * @propname: name of the property containing the string list
- * @return:
+ * Return:
  *   number of strings in the list, or -ve error value if not found
  */
 int dev_read_string_count(const struct udevice *dev, const char *propname);
@@ -386,8 +386,9 @@ int dev_read_string_count(const struct udevice *dev, const char *propname);
  * @propname: name of the property containing the string list
  * @listp: returns an allocated, NULL-terminated list of strings if the return
  *	value is > 0, else is set to NULL
- * @return number of strings in list, 0 if none, -ENOMEM if out of memory,
- *	-ENOENT if no such property
+ * Return:
+ * number of strings in list, 0 if none, -ENOMEM if out of memory,
+ * -ENOENT if no such property
  */
 int dev_read_string_list(const struct udevice *dev, const char *propname,
 			 const char ***listp);
@@ -402,19 +403,17 @@ int dev_read_string_list(const struct udevice *dev, const char *propname,
  * Caller is responsible to call of_node_put() on the returned out_args->np
  * pointer.
  *
- * Example:
+ * Example: ::
  *
- * phandle1: node1 {
- *	#list-cells = <2>;
- * }
- *
- * phandle2: node2 {
- *	#list-cells = <1>;
- * }
- *
- * node3 {
- *	list = <&phandle1 1 2 &phandle2 3>;
- * }
+ *   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:
  * dev_read_phandle_with_args(dev, "list", "#list-cells", 0, 1, &args);
@@ -422,10 +421,10 @@ int dev_read_string_list(const struct udevice *dev, const char *propname,
  * @dev:	device whose node containing a list
  * @list_name:	property name that contains a list
  * @cells_name:	property name that specifies phandles' arguments count
- * @cells_count: Cell count to use if @cells_name is NULL
+ * @cell_count: Cell count to use if @cells_name is NULL
  * @index:	index of a phandle to parse out
  * @out_args:	optional pointer to output arguments structure (will be filled)
- * @return 0 on success (with @out_args filled out if not NULL), -ENOENT if
+ * Return: 0 on success (with @out_args filled out if not NULL), -ENOENT if
  *	@list_name does not exist, -EINVAL if a phandle was not found,
  *	@cells_name could not be found, the arguments were truncated or there
  *	were too many arguments.
@@ -441,12 +440,11 @@ int dev_read_phandle_with_args(const struct udevice *dev, const char *list_name,
  * For example, this allows to allocate the right amount of memory to keep
  * clock's reference contained into the "clocks" property.
  *
- *
  * @dev:	device whose node containing a list
  * @list_name:	property name that contains a list
  * @cells_name:	property name that specifies phandles' arguments count
- * @cells_count: Cell count to use if @cells_name is NULL
- * @Returns number of phandle found on success, on error returns appropriate
+ * @cell_count: Cell count to use if @cells_name is NULL
+ * Return: number of phandle found on success, on error returns appropriate
  * errno value.
  */
 
@@ -461,7 +459,7 @@ int dev_count_phandle_with_args(const struct udevice *dev,
  * which controls the given node.
  *
  * @dev: device to check
- * @return number of address cells this node uses
+ * Return: number of address cells this node uses
  */
 int dev_read_addr_cells(const struct udevice *dev);
 
@@ -472,7 +470,7 @@ int dev_read_addr_cells(const struct udevice *dev);
  * which controls the given node.
  *
  * @dev: device to check
- * @return number of size cells this node uses
+ * Return: number of size cells this node uses
  */
 int dev_read_size_cells(const struct udevice *dev);
 
@@ -482,7 +480,7 @@ int dev_read_size_cells(const struct udevice *dev);
  * This function matches fdt_address_cells().
  *
  * @dev: device to check
- * @return number of address cells this node uses
+ * Return: number of address cells this node uses
  */
 int dev_read_simple_addr_cells(const struct udevice *dev);
 
@@ -492,7 +490,7 @@ int dev_read_simple_addr_cells(const struct udevice *dev);
  * This function matches fdt_size_cells().
  *
  * @dev: device to check
- * @return number of size cells this node uses
+ * Return: number of size cells this node uses
  */
 int dev_read_simple_size_cells(const struct udevice *dev);
 
@@ -500,7 +498,7 @@ int dev_read_simple_size_cells(const struct udevice *dev);
  * dev_read_phandle() - Get the phandle from a device
  *
  * @dev: device to check
- * @return phandle (1 or greater), or 0 if no phandle or other error
+ * Return: phandle (1 or greater), or 0 if no phandle or other error
  */
 int dev_read_phandle(const struct udevice *dev);
 
@@ -510,7 +508,7 @@ int dev_read_phandle(const struct udevice *dev);
  * @dev: device to check
  * @propname: property to read
  * @lenp: place to put length on success
- * @return pointer to property, or NULL if not found
+ * Return: pointer to property, or NULL if not found
  */
 const void *dev_read_prop(const struct udevice *dev, const char *propname,
 			  int *lenp);
@@ -523,7 +521,7 @@ const void *dev_read_prop(const struct udevice *dev, const char *propname,
  *
  * @dev: device to check
  * @prop: place to put argument reference
- * @return 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
+ * Return: 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
  */
 int dev_read_first_prop(const struct udevice *dev, struct ofprop *prop);
 
@@ -534,7 +532,7 @@ int dev_read_first_prop(const struct udevice *dev, struct ofprop *prop);
  * and read all the property with dev_read_prop_by_prop().
  *
  * @prop: reference of current argument and place to put reference of next one
- * @return 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
+ * Return: 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
  */
 int dev_read_next_prop(struct ofprop *prop);
 
@@ -546,7 +544,7 @@ int dev_read_next_prop(struct ofprop *prop);
  * @prop: reference on property
  * @propname: If non-NULL, place to property name on success,
  * @lenp: If non-NULL, place to put length on success
- * @return 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
+ * Return: 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
  */
 const void *dev_read_prop_by_prop(struct ofprop *prop,
 				  const char **propname, int *lenp);
@@ -560,7 +558,7 @@ const void *dev_read_prop_by_prop(struct ofprop *prop,
  *
  * @dev: device to look up
  * @devnump: set to the sequence number if one is found
- * @return 0 if a sequence was found, -ve if not
+ * Return: 0 if a sequence was found, -ve if not
  */
 int dev_read_alias_seq(const struct udevice *dev, int *devnump);
 
@@ -576,7 +574,7 @@ int dev_read_alias_seq(const struct udevice *dev, int *devnump);
  * @propname:	name of the property to read
  * @out_values:	pointer to return value, modified only if return value is 0
  * @sz:		number of array elements to read
- * @return 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 -EOVERFLOW if the property data isn't
  * large enough.
  */
@@ -587,7 +585,7 @@ int dev_read_u32_array(const struct udevice *dev, const char *propname,
  * dev_read_first_subnode() - find the first subnode of a device's node
  *
  * @dev: device to look up
- * @return reference to the first subnode (which can be invalid if the device's
+ * Return: reference to the first subnode (which can be invalid if the device's
  * node has no subnodes)
  */
 ofnode dev_read_first_subnode(const struct udevice *dev);
@@ -596,7 +594,7 @@ ofnode dev_read_first_subnode(const struct udevice *dev);
  * ofnode_next_subnode() - find the next sibling of a subnode
  *
  * @node:	valid reference to previous node (sibling)
- * @return reference to the next subnode (which can be invalid if the node
+ * Return: reference to the next subnode (which can be invalid if the node
  * has no more siblings)
  */
 ofnode dev_read_next_subnode(ofnode node);
@@ -612,8 +610,9 @@ ofnode dev_read_next_subnode(ofnode node);
  * @dev: device to look up
  * @propname: name of property to find
  * @sz: number of array elements
- * @return pointer to byte array if found, or NULL if the property is not
- *		found or there is not enough data
+ * Return:
+ * pointer to byte array if found, or NULL if the property is not found or
+ * there is not enough data
  */
 const uint8_t *dev_read_u8_array_ptr(const struct udevice *dev,
 				     const char *propname, size_t sz);
@@ -627,7 +626,7 @@ const uint8_t *dev_read_u8_array_ptr(const struct udevice *dev,
  * by default.
  *
  * @dev: device to examine
- * @return integer value 0 (not enabled) or 1 (enabled)
+ * Return: integer value 0 (not enabled) or 1 (enabled)
  */
 int dev_read_enabled(const struct udevice *dev);
 
@@ -635,9 +634,9 @@ int dev_read_enabled(const struct udevice *dev);
  * dev_read_resource() - obtain an indexed resource from a device.
  *
  * @dev: device to examine
- * @index index of the resource to retrieve (0 = first)
- * @res returns the resource
- * @return 0 if ok, negative on error
+ * @index: index of the resource to retrieve (0 = first)
+ * @res: returns the resource
+ * Return: 0 if ok, negative on error
  */
 int dev_read_resource(const struct udevice *dev, uint index,
 		      struct resource *res);
@@ -648,7 +647,7 @@ int dev_read_resource(const struct udevice *dev, uint index,
  * @dev: device to examine
  * @name: name of the resource to retrieve
  * @res: returns the resource
- * @return 0 if ok, negative on error
+ * Return: 0 if ok, negative on error
  */
 int dev_read_resource_byname(const struct udevice *dev, const char *name,
 			     struct resource *res);
@@ -662,7 +661,7 @@ int dev_read_resource_byname(const struct udevice *dev, const char *name,
  *
  * @dev: device giving the context in which to translate the address
  * @in_addr: pointer to the address to translate
- * @return the translated address; OF_BAD_ADDR on error
+ * Return: the translated address; OF_BAD_ADDR on error
  */
 u64 dev_translate_address(const struct udevice *dev, const fdt32_t *in_addr);
 
@@ -675,7 +674,7 @@ u64 dev_translate_address(const struct udevice *dev, const fdt32_t *in_addr);
  *
  * @dev: device giving the context in which to translate the DMA address
  * @in_addr: pointer to the DMA address to translate
- * @return the translated DMA address; OF_BAD_ADDR on error
+ * Return: the translated DMA address; OF_BAD_ADDR on error
  */
 u64 dev_translate_dma_address(const struct udevice *dev,
 			      const fdt32_t *in_addr);
@@ -690,7 +689,7 @@ u64 dev_translate_dma_address(const struct udevice *dev,
  * @cpu: base address for CPU's view of memory
  * @bus: base address for BUS's view of memory
  * @size: size of the address space
- * @return 0 if ok, negative on error
+ * Return: 0 if ok, negative on error
  */
 int dev_get_dma_range(const struct udevice *dev, phys_addr_t *cpu,
 		      dma_addr_t *bus, u64 *size);
@@ -701,15 +700,15 @@ int dev_get_dma_range(const struct udevice *dev, phys_addr_t *cpu,
  *
  * The function travels the lookup table to get the highest alias id for the
  * given alias stem.
- * @return alias ID, if found, else -1
+ * Return: alias ID, if found, else -1
  */
 int dev_read_alias_highest_id(const char *stem);
 
 /**
  * dev_get_child_count() - get the child count of a device
  *
- * @dev: device to use for interation (struct udevice *)
- * @return the count of child subnode
+ * @dev: device to use for interation (`struct udevice *`)
+ * Return: the count of child subnode
  */
 int dev_get_child_count(const struct udevice *dev);
 
@@ -720,8 +719,8 @@ int dev_get_child_count(const struct udevice *dev);
  * range for this node.
  *
  * @dev: device to examine
- * @res returns the resource
- * @return 0 if ok, negative on error
+ * @res: returns the resource
+ * Return: 0 if ok, negative on error
  */
 int dev_read_pci_bus_range(const struct udevice *dev, struct resource *res);
 
@@ -737,7 +736,7 @@ int dev_read_pci_bus_range(const struct udevice *dev, struct resource *res);
  *       one or more display timing nodes.
  * @index: index number to read (0=first timing subnode)
  * @config: place to put timings
- * @return 0 if OK, -FDT_ERR_NOTFOUND if not found
+ * Return: 0 if OK, -FDT_ERR_NOTFOUND if not found
  */
 int dev_decode_display_timing(const struct udevice *dev, int index,
 			      struct display_timing *config);
@@ -1100,7 +1099,7 @@ static inline int dev_decode_display_timing(const struct udevice *dev,
  * device-tree node.
  *
  * @subnode: ofnode holding the current subnode
- * @dev: device to use for interation (struct udevice *)
+ * @dev: device to use for interation (`struct udevice *`)
  */
 #define dev_for_each_subnode(subnode, dev) \
 	for (subnode = dev_read_first_subnode(dev); \
@@ -1114,7 +1113,7 @@ static inline int dev_decode_display_timing(const struct udevice *dev,
  * device-tree node.
  *
  * @prop: struct ofprop holding the current property
- * @dev: device to use for interation (struct udevice *)
+ * @dev: device to use for interation (`struct udevice *`)
  */
 #define dev_for_each_property(prop, dev) \
 	for (int ret_prop = dev_read_first_prop(dev, &prop); \
-- 
2.25.1

[PATCH 8/9] doc: add include/dm/of*.h to the HTML documentation

[Patrick Delaunay]

Correct Sphinx style comments in include/dm/ofnode.h
and add the device tree node API to the HTML documentation;
the ofnode functions are compatible with Live tree or with flat
device tree.

Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
---

 doc/api/dm.rst         |   9 ++
 include/dm/of.h        |  13 +-
 include/dm/of_access.h | 141 ++++++++---------
 include/dm/of_addr.h   |  33 ++--
 include/dm/of_extra.h  |  48 +++---
 include/dm/ofnode.h    | 332 +++++++++++++++++++++--------------------
 6 files changed, 297 insertions(+), 279 deletions(-)

diff --git a/doc/api/dm.rst b/doc/api/dm.rst
index 19a473f1f0..5bb66f2f50 100644
--- a/doc/api/dm.rst
+++ b/doc/api/dm.rst
@@ -17,3 +17,12 @@ Device
 .. kernel-doc:: include/dm/device.h
 .. kernel-doc:: include/dm/devres.h
 .. kernel-doc:: include/dm/read.h
+
+Device tree
+-----------
+
+.. kernel-doc:: include/dm/of.h
+.. kernel-doc:: include/dm/ofnode.h
+.. kernel-doc:: include/dm/of_extra.h
+.. kernel-doc:: include/dm/of_access.h
+.. kernel-doc:: include/dm/of_addr.h
diff --git a/include/dm/of.h b/include/dm/of.h
index 5cb6f44a6c..963e1de44c 100644
--- a/include/dm/of.h
+++ b/include/dm/of.h
@@ -58,14 +58,13 @@ struct device_node {
  * struct of_phandle_args - structure to hold phandle and arguments
  *
  * This is used when decoding a phandle in a device tree property. Typically
- * these look like this:
+ * these look like this: ::
  *
- * wibble {
- *    phandle = <5>;
- * };
- *
- * ...
- * some-prop = <&wibble 1 2 3>
+ *   wibble {
+ *     phandle = <5>;
+ *   };
+ *   ...
+ *   some-prop = <&wibble 1 2 3>
  *
  * Here &node is the phandle of the node 'wibble', i.e. 5. There are three
  * arguments: 1, 2, 3.
diff --git a/include/dm/of_access.h b/include/dm/of_access.h
index cc382b1671..2beb3797d7 100644
--- a/include/dm/of_access.h
+++ b/include/dm/of_access.h
@@ -44,7 +44,7 @@ static inline void of_node_put(const struct device_node *np) { }
  * which controls the given node.
  *
  * @np: Node pointer to check
- * @return number of address cells this node uses
+ * Return: number of address cells this node uses
  */
 int of_n_addr_cells(const struct device_node *np);
 
@@ -55,7 +55,7 @@ int of_n_addr_cells(const struct device_node *np);
  * which controls the given node.
  *
  * @np: Node pointer to check
- * @return number of size cells this node uses
+ * Return: number of size cells this node uses
  */
 int of_n_size_cells(const struct device_node *np);
 
@@ -65,7 +65,7 @@ int of_n_size_cells(const struct device_node *np);
  * This function matches fdt_address_cells().
  *
  * @np: Node pointer to check
- * @return value of #address-cells property in this node, or 2 if none
+ * Return: value of #address-cells property in this node, or 2 if none
  */
 int of_simple_addr_cells(const struct device_node *np);
 
@@ -75,7 +75,7 @@ int of_simple_addr_cells(const struct device_node *np);
  * This function matches fdt_size_cells().
  *
  * @np: Node pointer to check
- * @return value of #size-cells property in this node, or 2 if none
+ * Return: value of #size-cells property in this node, or 2 if none
  */
 int of_simple_size_cells(const struct device_node *np);
 
@@ -85,7 +85,7 @@ int of_simple_size_cells(const struct device_node *np);
  * @np: Pointer to device node holding property
  * @name: Name of property
  * @lenp: If non-NULL, returns length of property
- * @return pointer to property, or NULL if not found
+ * Return: pointer to property, or NULL if not found
  */
 struct property *of_find_property(const struct device_node *np,
 				  const char *name, int *lenp);
@@ -98,7 +98,7 @@ struct property *of_find_property(const struct device_node *np,
  * @np: Pointer to device node holding property
  * @name: Name of property
  * @lenp: If non-NULL, returns length of property
- * @return pointer to property value, or NULL if not found
+ * Return: pointer to property value, or NULL if not found
  */
 const void *of_get_property(const struct device_node *np, const char *name,
 			    int *lenp);
@@ -110,7 +110,7 @@ const void *of_get_property(const struct device_node *np, const char *name,
  * and read all the property with of_get_next_property_by_prop().
  *
  * @np: Pointer to device node
- * @return pointer to property or NULL if not found
+ * Return: pointer to property or NULL if not found
  */
 const struct property *of_get_first_property(const struct device_node *np);
 
@@ -122,7 +122,7 @@ const struct property *of_get_first_property(const struct device_node *np);
  *
  * @np: Pointer to device node
  * @property: pointer of the current property
- * @return pointer to next property or NULL if not found
+ * Return: pointer to next property or NULL if not found
  */
 const struct property *of_get_next_property(const struct device_node *np,
 					    const struct property *property);
@@ -132,11 +132,11 @@ const struct property *of_get_next_property(const struct device_node *np,
  *
  * Get value for the property identified by node and property pointer.
  *
- * @node: node to read
+ * @np: Pointer to device node
  * @property: pointer of the property to read
- * @propname: place to property name on success
+ * @name: place to property name on success
  * @lenp: place to put length on success
- * @return pointer to property value or NULL if error
+ * Return: pointer to property value or NULL if error
  */
 const void *of_get_property_by_prop(const struct device_node *np,
 				    const struct property *property,
@@ -145,7 +145,7 @@ const void *of_get_property_by_prop(const struct device_node *np,
 
 /**
  * of_device_is_compatible() - Check if the node matches given constraints
- * @device: pointer to node
+ * @np: Pointer to device node
  * @compat: required compatible string, NULL or "" for any match
  * @type: required device_type value, NULL or "" for any match
  * @name: required node name, NULL or "" for any match
@@ -154,7 +154,7 @@ const void *of_get_property_by_prop(const struct device_node *np,
  * properties of the given @device. A constraints can be skipped by
  * passing NULL or an empty string as the constraint.
  *
- * @return 0 for no match, and a positive integer on match. The return
+ * Return: 0 for no match, and a positive integer on match. The return
  * value is a relative score with larger values indicating better
  * matches. The score is weighted for the most specific compatible value
  * to get the highest score. Matching type is next, followed by matching
@@ -179,9 +179,9 @@ int of_device_is_compatible(const struct device_node *np, const char *compat,
 /**
  * of_device_is_available() - check if a device is available for use
  *
- * @device: Node to check for availability
+ * @np: Pointer to device node to check for availability
  *
- * @return true if the status property is absent or set to "okay", false
+ * Return: true if the status property is absent or set to "okay", false
  * otherwise
  */
 bool of_device_is_available(const struct device_node *np);
@@ -189,8 +189,8 @@ bool of_device_is_available(const struct device_node *np);
 /**
  * of_get_parent() - Get a node's parent, if any
  *
- * @node: Node to check
- * @eturns a node pointer, or NULL if none
+ * @np: Pointer to device node  to check
+ * Return: a node pointer, or NULL if none
  */
 struct device_node *of_get_parent(const struct device_node *np);
 
@@ -208,7 +208,7 @@ struct device_node *of_get_parent(const struct device_node *np);
  *	foo		Valid alias
  *	foo/bar		Valid alias + relative path
  *
- * @return a node pointer or NULL if not found
+ * Return: a node pointer or NULL if not found
  */
 struct device_node *of_find_node_opts_by_path(const char *path,
 					      const char **opts);
@@ -228,7 +228,7 @@ static inline struct device_node *of_find_node_by_path(const char *path)
  * @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 node pointer or NULL if not found
+ * Return: node pointer or NULL if not found
  */
 struct device_node *of_find_compatible_node(struct device_node *from,
 				const char *type, const char *compatible);
@@ -243,7 +243,7 @@ struct device_node *of_find_compatible_node(struct device_node *from,
  * @propname: property name to check
  * @propval: property value to search for
  * @proplen: length of the value in propval
- * @return node pointer or NULL if not found
+ * Return: node pointer or NULL if not found
  */
 struct device_node *of_find_node_by_prop_value(struct device_node *from,
 					       const char *propname,
@@ -254,7 +254,7 @@ struct device_node *of_find_node_by_prop_value(struct device_node *from,
  *
  * @handle:	phandle of the node to find
  *
- * @return node pointer, or NULL if not found
+ * Return: node pointer, or NULL if not found
  */
 struct device_node *of_find_node_by_phandle(phandle handle);
 
@@ -268,7 +268,7 @@ struct device_node *of_find_node_by_phandle(phandle handle);
  * @propname:	name of the property to be searched.
  * @outp:	pointer to return value, modified only if return value is 0.
  *
- * @return 0 on success, -EINVAL if the property does not exist,
+ * 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.
  */
@@ -286,9 +286,10 @@ int of_read_u32(const struct device_node *np, const char *propname, u32 *outp);
  * @index:	index of the u32 in the list of values
  * @outp:	pointer to return value, modified only if return value is 0.
  *
- * @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.
+ * 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.
  */
 int of_read_u32_index(const struct device_node *np, const char *propname,
 		      int index, u32 *outp);
@@ -303,9 +304,10 @@ int of_read_u32_index(const struct device_node *np, const char *propname,
  * @propname:	name of the property to be searched.
  * @outp:	pointer to return value, modified only if return value is 0.
  *
- * @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.
+ * 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.
  */
 int of_read_u64(const struct device_node *np, const char *propname, u64 *outp);
 
@@ -319,8 +321,9 @@ int of_read_u64(const struct device_node *np, const char *propname, u64 *outp);
  * @propname:	name of the property to be searched.
  * @out_values:	pointer to return value, modified only if return value is 0.
  * @sz:		number of array elements to read
- * @return 0 on success, -EINVAL if the property does not exist, -ENODATA
- * if property does not have a value, and -EOVERFLOW is longer than sz.
+ * Return:
+ *   0 on success, -EINVAL if the property does not exist, -ENODATA
+ *   if property does not have a value, and -EOVERFLOW is longer than sz.
  */
 int of_read_u32_array(const struct device_node *np, const char *propname,
 		      u32 *out_values, size_t sz);
@@ -334,8 +337,9 @@ int of_read_u32_array(const struct device_node *np, const char *propname,
  * @np: pointer to node containing string list property
  * @propname: string list property name
  * @string: pointer to string to search for in string list
- * @return 0 on success, -EINVAL if the property does not exist, -ENODATA
- * if property does not have a value, and -EOVERFLOW is longer than sz.
+ * Return:
+ *   0 on success, -EINVAL if the property does not exist, -ENODATA
+ *   if property does not have a value, and -EOVERFLOW is longer than sz.
  */
 int of_property_match_string(const struct device_node *np, const char *propname,
 			     const char *string);
@@ -350,15 +354,17 @@ int of_property_read_string_helper(const struct device_node *np,
  * @np:		device node from which the property value is to be read.
  * @propname:	name of the property to be searched.
  * @index:	index of the string in the list of strings
- * @out_string:	pointer to null terminated return string, modified only if
+ * @output:	pointer to null terminated return string, modified only if
  *		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) in the list of strings
  * contained in that property.
- * 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.
+ *
+ * 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.
  */
@@ -377,10 +383,12 @@ 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 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)
@@ -395,8 +403,9 @@ static inline int of_property_count_strings(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
- * of_node_put() on it when done.
+ * 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,
 				     const char *phandle_name, int index);
@@ -410,10 +419,11 @@ struct device_node *of_parse_phandle(const struct device_node *np,
  * @cells_count: Cell count to use if @cells_name is NULL
  * @index:	index of a phandle to parse out
  * @out_args:	optional pointer to output arguments structure (will be filled)
- * @return 0 on success (with @out_args filled out if not NULL), -ENOENT if
- *	@list_name does not exist, -EINVAL if a phandle was not found,
- *	@cells_name could not be found, the arguments were truncated or there
- *	were too many arguments.
+ * Return:
+ *   0 on success (with @out_args filled out if not NULL), -ENOENT if
+ *   @list_name does not exist, -EINVAL if a phandle was not found,
+ *   @cells_name could not be found, the arguments were truncated or there
+ *   were too many arguments.
  *
  * This function is useful to parse lists of phandles and their arguments.
  * Returns 0 on success and fills out_args, on error returns appropriate
@@ -422,19 +432,17 @@ struct device_node *of_parse_phandle(const struct device_node *np,
  * Caller is responsible to call of_node_put() on the returned out_args->np
  * pointer.
  *
- * Example:
+ * Example: ::
  *
- * phandle1: node1 {
- *	#list-cells = <2>;
- * }
- *
- * phandle2: node2 {
- *	#list-cells = <1>;
- * }
- *
- * node3 {
- *	list = <&phandle1 1 2 &phandle2 3>;
- * }
+ *   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);
@@ -451,14 +459,13 @@ int of_parse_phandle_with_args(const struct device_node *np,
  * @list_name:	property name that contains a list
  * @cells_name:	property name that specifies phandles' arguments count
  * @cells_count: Cell count to use if @cells_name is NULL
- * @return number of phandle found, -ENOENT if
- *	@list_name does not exist, -EINVAL if a phandle was not found,
- *	@cells_name could not be found, the arguments were truncated or there
- *	were too many arguments.
+ * Return:
+ *   number of phandle found, -ENOENT if @list_name does not exist,
+ *   -EINVAL if a phandle was not found, @cells_name could not be found,
+ *   the arguments were truncated or there were too many arguments.
  *
  * Returns number of phandle found on success, on error returns appropriate
  * errno value.
- *
  */
 int of_count_phandle_with_args(const struct device_node *np,
 			       const char *list_name, const char *cells_name,
@@ -471,7 +478,7 @@ int of_count_phandle_with_args(const struct device_node *np,
  * the lookup table with the properties.  It returns the number of alias
  * properties found, or an error code in case of failure.
  *
- * @return 9 if OK, -ENOMEM if not enough memory
+ * Return: 9 if OK, -ENOMEM if not enough memory
  */
 int of_alias_scan(void);
 
@@ -483,7 +490,7 @@ int of_alias_scan(void);
  *
  * @np:		Pointer to the given device_node
  * @stem:	Alias stem of the given device_node
- * @return alias ID, if found, else -ENODEV
+ * Return: alias ID, if found, else -ENODEV
  */
 int of_alias_get_id(const struct device_node *np, const char *stem);
 
@@ -493,14 +500,14 @@ int of_alias_get_id(const struct device_node *np, const char *stem);
  *
  * The function travels the lookup table to get the highest alias id for the
  * given alias stem.
- * @return alias ID, if found, else -1
+ * Return: alias ID, if found, else -1
  */
 int of_alias_get_highest_id(const char *stem);
 
 /**
  * of_get_stdout() - Get node to use for stdout
  *
- * @return node referred to by stdout-path alias, or NULL if none
+ * Return: node referred to by stdout-path alias, or NULL if none
  */
 struct device_node *of_get_stdout(void);
 
diff --git a/include/dm/of_addr.h b/include/dm/of_addr.h
index ee21d5cf4f..e7f3a28081 100644
--- a/include/dm/of_addr.h
+++ b/include/dm/of_addr.h
@@ -20,11 +20,11 @@
  * that can be mapped to a cpu physical address). This is not really specified
  * that way, but this is traditionally the way IBM at least do things
  *
- * @np: node to check
+ * @np: pointer to node to check
  * @in_addr: pointer to input address
- * @return translated address or OF_BAD_ADDR on error
+ * Return: translated address or OF_BAD_ADDR on error
  */
-u64 of_translate_address(const struct device_node *no, const __be32 *in_addr);
+u64 of_translate_address(const struct device_node *np, const __be32 *in_addr);
 
 /**
  * of_translate_dma_address() - translate a device-tree DMA address to a CPU
@@ -38,11 +38,11 @@ u64 of_translate_address(const struct device_node *no, const __be32 *in_addr);
  * that can be mapped to a cpu physical address). This is not really specified
  * that way, but this is traditionally the way IBM at least do things
  *
- * @np: node to check
+ * @np: ne
  * @in_addr: pointer to input DMA address
- * @return translated DMA address or OF_BAD_ADDR on error
+ * Return: translated DMA address or OF_BAD_ADDR on error
  */
-u64 of_translate_dma_address(const struct device_node *no, const __be32 *in_addr);
+u64 of_translate_dma_address(const struct device_node *np, const __be32 *in_addr);
 
 
 /**
@@ -51,14 +51,13 @@ u64 of_translate_dma_address(const struct device_node *no, const __be32 *in_addr
  * Get DMA ranges for a specifc node, this is useful to perform bus->cpu and
  * cpu->bus address translations
  *
- * @param blob		Pointer to device tree blob
- * @param node_offset	Node DT offset
- * @param cpu		Pointer to variable storing the range's cpu address
- * @param bus		Pointer to variable storing the range's bus address
- * @param size		Pointer to variable storing the range's size
- * @return translated DMA address or OF_BAD_ADDR on error
+ * @np:		Pointer to device tree blob
+ * @cpu:	Pointer to variable storing the range's cpu address
+ * @bus:	Pointer to variable storing the range's bus address
+ * @size:	Pointer to variable storing the range's size
+ * Return: translated DMA address or OF_BAD_ADDR on error
  */
-int of_get_dma_range(const struct device_node *dev, phys_addr_t *cpu,
+int of_get_dma_range(const struct device_node *np, phys_addr_t *cpu,
 		     dma_addr_t *bus, u64 *size);
 
 /**
@@ -72,9 +71,9 @@ int of_get_dma_range(const struct device_node *dev, phys_addr_t *cpu,
  * @index: Index of address to read (0 = first)
  * @size: place to put size on success
  * @flags: place to put flags on success
- * @return pointer to address which can be read
+ * Return: pointer to address which can be read
  */
-const __be32 *of_get_address(const struct device_node *no, int index,
+const __be32 *of_get_address(const struct device_node *np, int index,
 			     u64 *size, unsigned int *flags);
 
 struct resource;
@@ -90,9 +89,9 @@ struct resource;
  * @np: node to check
  * @index: index of address to read (0 = first)
  * @r: place to put resource information
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
-int of_address_to_resource(const struct device_node *no, int index,
+int of_address_to_resource(const struct device_node *np, int index,
 			   struct resource *r);
 
 #endif
diff --git a/include/dm/of_extra.h b/include/dm/of_extra.h
index c2498aa585..17e85a819b 100644
--- a/include/dm/of_extra.h
+++ b/include/dm/of_extra.h
@@ -41,11 +41,11 @@ struct fmap_entry {
 };
 
 /**
- * Read a flash entry from the fdt
+ * ofnode_read_fmap_entry() - Read a flash entry from the fdt
  *
- * @param node		Reference to node to read
- * @param entry		Place to put offset and size of this node
- * @return 0 if ok, -ve on error
+ * @node:	Reference to node to read
+ * @entry:	Place to put offset and size of this node
+ * Return: 0 if ok, -ve on error
  */
 int ofnode_read_fmap_entry(ofnode node, struct fmap_entry *entry);
 
@@ -58,11 +58,11 @@ int ofnode_read_fmap_entry(ofnode node, struct fmap_entry *entry);
  * The property must hold one address with a length. This is only tested on
  * 32-bit machines.
  *
- * @param node		ofnode to examine
- * @param prop_name	name of property to find
- * @param basep		Returns base address of region
- * @param size		Returns size of region
- * @return 0 if ok, -1 on error (property not found)
+ * @node:	ofnode to examine
+ * @prop_name:	name of property to find
+ * @basep:	Returns base address of region
+ * @sizep:	Returns size of region
+ * Return: 0 if ok, -1 on error (property not found)
  */
 int ofnode_decode_region(ofnode node, const char *prop_name, fdt_addr_t *basep,
 			 fdt_size_t *sizep);
@@ -81,14 +81,14 @@ int ofnode_decode_region(ofnode node, const char *prop_name, fdt_addr_t *basep,
  * The property value must have an offset and a size. The function checks
  * that the region is entirely within the memory bank.5
  *
- * @param node		ofnode containing the properties (-1 for /config)
- * @param mem_type	Type of memory to use, which is a name, such as
- *			"u-boot" or "kernel".
- * @param suffix	String to append to the memory/offset
- *			property names
- * @param basep		Returns base of region
- * @param sizep		Returns size of region
- * @return 0 if OK, -ive on error
+ * @config_node:	ofnode containing the properties (invalid for "/config")
+ * @mem_type:	Type of memory to use, which is a name, such as
+ *		"u-boot" or "kernel".
+ * @suffix:	String to append to the memory/offset
+ *		property names
+ * @basep:	Returns base of region
+ * @sizep:	Returns size of region
+ * Return: 0 if OK, -ive on error
  */
 int ofnode_decode_memory_region(ofnode config_node, const char *mem_type,
 				const char *suffix, fdt_addr_t *basep,
@@ -102,15 +102,15 @@ int ofnode_decode_memory_region(ofnode config_node, const char *mem_type,
  *
  * This function supports the following two DT bindings:
  * - the new DT binding, where 'fixed-link' is a sub-node of the
- *   Ethernet device
+ * Ethernet device
  * - the old DT binding, where 'fixed-link' is a property with 5
- *   cells encoding various information about the fixed PHY
+ * cells encoding various information about the fixed PHY
  *
  * If both new and old bindings exist, the new one is preferred.
  *
- * @param eth_node	ofnode containing the fixed-link subnode/property
- * @param phy_node	if fixed-link PHY detected, containing the PHY ofnode
- * @return true if a fixed-link pseudo-PHY device exists, false otherwise
+ * @eth_node:	ofnode containing the fixed-link subnode/property
+ * @phy_node:	if fixed-link PHY detected, containing the PHY ofnode
+ * Return: true if a fixed-link pseudo-PHY device exists, false otherwise
  */
 bool ofnode_phy_is_fixed_link(ofnode eth_node, ofnode *phy_node);
 
@@ -123,8 +123,8 @@ bool ofnode_phy_is_fixed_link(ofnode eth_node, ofnode *phy_node);
  * is connected to an on-board PHY or an SFP cage, and is not relevant when it
  * has a fixed link (in that case, in-band autoneg should not be used).
  *
- * @param eth_node	ofnode belonging to the Ethernet controller
- * @return true if in-band autoneg should be used, false otherwise
+ * @eth_node:	ofnode belonging to the Ethernet controller
+ * Return: true if in-band autoneg should be used, false otherwise
  */
 bool ofnode_eth_uses_inband_aneg(ofnode eth_node);
 
diff --git a/include/dm/ofnode.h b/include/dm/ofnode.h
index 6601bd8318..8b4f628856 100644
--- a/include/dm/ofnode.h
+++ b/include/dm/ofnode.h
@@ -19,7 +19,7 @@
 struct resource;
 
 /**
- * ofnode - reference to a device tree node
+ * typedef union ofnode_union ofnode - reference to a device tree node
  *
  * This union can hold either a straightforward pointer to a struct device_node
  * in the live device tree, or an offset within the flat device tree. In the
@@ -27,7 +27,7 @@ struct resource;
  *
  * Thus we can reference nodes in both the live tree (once available) and the
  * flat tree (until then). Functions are available to translate between an
- * ofnode and either an offset or a struct device_node *.
+ * ofnode and either an offset or a `struct device_node *`.
  *
  * The reference can also hold a null offset, in which case the pointer value
  * here is NULL. This corresponds to a struct device_node * value of
@@ -61,7 +61,7 @@ struct ofnode_phandle_args {
 };
 
 /**
- * ofprop - reference to a property of a device tree node
+ * struct ofprop - reference to a property of a device tree node
  *
  * This struct hold the reference on one property of one node,
  * using struct ofnode and an offset within the flat device tree or either
@@ -91,7 +91,7 @@ struct ofprop {
  * This cannot be called if the reference contains an offset.
  *
  * @node: Reference containing struct device_node * (possibly invalid)
- * @return pointer to device node (can be NULL)
+ * Return: pointer to device node (can be NULL)
  */
 static inline const struct device_node *ofnode_to_np(ofnode node)
 {
@@ -108,7 +108,7 @@ static inline const struct device_node *ofnode_to_np(ofnode node)
  * This cannot be called if the reference contains a node pointer.
  *
  * @node: Reference containing offset (possibly invalid)
- * @return DT offset (can be -1)
+ * Return: DT offset (can be -1)
  */
 static inline int ofnode_to_offset(ofnode node)
 {
@@ -122,7 +122,8 @@ static inline int ofnode_to_offset(ofnode node)
 /**
  * ofnode_valid() - check if an ofnode is valid
  *
- * @return true if the reference contains a valid ofnode, false if it is NULL
+ * @node: Reference containing offset (possibly invalid)
+ * Return: true if the reference contains a valid ofnode, false if it is NULL
  */
 static inline bool ofnode_valid(ofnode node)
 {
@@ -136,7 +137,7 @@ static inline bool ofnode_valid(ofnode node)
  * offset_to_ofnode() - convert a DT offset to an ofnode
  *
  * @of_offset: DT offset (either valid, or -1)
- * @return reference to the associated DT offset
+ * Return: reference to the associated DT offset
  */
 static inline ofnode offset_to_ofnode(int of_offset)
 {
@@ -154,7 +155,7 @@ static inline ofnode offset_to_ofnode(int of_offset)
  * np_to_ofnode() - convert a node pointer to an ofnode
  *
  * @np: Live node pointer (can be NULL)
- * @return reference to the associated node pointer
+ * Return: reference to the associated node pointer
  */
 static inline ofnode np_to_ofnode(const struct device_node *np)
 {
@@ -173,7 +174,7 @@ static inline ofnode np_to_ofnode(const struct device_node *np)
  * is valid is not permitted.
  *
  * @node: reference to check (possibly invalid)
- * @return true if the reference is a live node pointer, false if it is a DT
+ * Return: true if the reference is a live node pointer, false if it is a DT
  * offset
  */
 static inline bool ofnode_is_np(ofnode node)
@@ -193,7 +194,9 @@ static inline bool ofnode_is_np(ofnode node)
 /**
  * ofnode_equal() - check if two references are equal
  *
- * @return true if equal, else false
+ * @ref1: first reference to check (possibly invalid)
+ * @ref2: second reference to check (possibly invalid)
+ * Return: true if equal, else false
  */
 static inline bool ofnode_equal(ofnode ref1, ofnode ref2)
 {
@@ -237,28 +240,28 @@ static inline ofnode ofnode_root(void)
  *
  * @node:	valid node reference that has to be compared
  * @name:	name that has to be compared with the node name
- * @return true if matches, false if it doesn't match
+ * Return: true if matches, false if it doesn't match
  */
 bool ofnode_name_eq(ofnode node, const char *name);
 
 /**
  * ofnode_read_u32() - Read a 32-bit integer from a property
  *
- * @ref:	valid node reference to read property from
+ * @node:	valid node reference to read property from
  * @propname:	name of the property to read from
  * @outp:	place to put value (if found)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int ofnode_read_u32(ofnode node, const char *propname, u32 *outp);
 
 /**
  * ofnode_read_u32_index() - Read a 32-bit integer from a multi-value property
  *
- * @ref:	valid node reference to read property from
+ * @node:	valid node reference to read property from
  * @propname:	name of the property to read from
  * @index:	index of the integer to return
  * @outp:	place to put value (if found)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int ofnode_read_u32_index(ofnode node, const char *propname, int index,
 			  u32 *outp);
@@ -266,47 +269,47 @@ int ofnode_read_u32_index(ofnode node, const char *propname, int index,
 /**
  * ofnode_read_s32() - Read a 32-bit integer from a property
  *
- * @ref:	valid node reference to read property from
+ * @node:	valid node reference to read property from
  * @propname:	name of the property to read from
  * @outp:	place to put value (if found)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 static inline int ofnode_read_s32(ofnode node, const char *propname,
-				  s32 *out_value)
+				  s32 *outp)
 {
-	return ofnode_read_u32(node, propname, (u32 *)out_value);
+	return ofnode_read_u32(node, propname, (u32 *)outp);
 }
 
 /**
  * ofnode_read_u32_default() - Read a 32-bit integer from a property
  *
- * @ref:	valid node reference to read property from
+ * @node:	valid node reference to read property from
  * @propname:	name of the property to read from
  * @def:	default value to return if the property has no value
- * @return property value, or @def if not found
+ * Return: property value, or @def if not found
  */
-u32 ofnode_read_u32_default(ofnode ref, const char *propname, u32 def);
+u32 ofnode_read_u32_default(ofnode node, const char *propname, u32 def);
 
 /**
  * ofnode_read_u32_index_default() - Read a 32-bit integer from a multi-value
  *                                   property
  *
- * @ref:	valid node reference to read property from
+ * @node:	valid node reference to read property from
  * @propname:	name of the property to read from
  * @index:	index of the integer to return
  * @def:	default value to return if the property has no value
- * @return property value, or @def if not found
+ * Return: property value, or @def if not found
  */
-u32 ofnode_read_u32_index_default(ofnode ref, const char *propname, int index,
+u32 ofnode_read_u32_index_default(ofnode node, const char *propname, int index,
 				  u32 def);
 
 /**
  * ofnode_read_s32_default() - Read a 32-bit integer from a property
  *
- * @ref:	valid node reference to read property from
+ * @node:	valid node reference to read property from
  * @propname:	name of the property to read from
  * @def:	default value to return if the property has no value
- * @return property value, or @def if not found
+ * Return: property value, or @def if not found
  */
 int ofnode_read_s32_default(ofnode node, const char *propname, s32 def);
 
@@ -316,17 +319,17 @@ int ofnode_read_s32_default(ofnode node, const char *propname, s32 def);
  * @node:	valid node reference to read property from
  * @propname:	name of the property to read from
  * @outp:	place to put value (if found)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int ofnode_read_u64(ofnode node, const char *propname, u64 *outp);
 
 /**
  * ofnode_read_u64_default() - Read a 64-bit integer from a property
  *
- * @ref:	valid node reference to read property from
+ * @node:	valid node reference to read property from
  * @propname:	name of the property to read from
  * @def:	default value to return if the property has no value
- * @return property value, or @def if not found
+ * Return: property value, or @def if not found
  */
 u64 ofnode_read_u64_default(ofnode node, const char *propname, u64 def);
 
@@ -336,8 +339,8 @@ u64 ofnode_read_u64_default(ofnode node, const char *propname, u64 def);
  * @node:	valid node reference to read property from
  * @propname:	name of the property to read
  * @sizep:	if non-NULL, returns the size of the property, or an error code
-		if not found
- * @return property value, or NULL if there is no such property
+ *              if not found
+ * Return: property value, or NULL if there is no such property
  */
 const void *ofnode_read_prop(ofnode node, const char *propname, int *sizep);
 
@@ -346,7 +349,7 @@ const void *ofnode_read_prop(ofnode node, const char *propname, int *sizep);
  *
  * @node:	valid node reference to read property from
  * @propname:	name of the property to read
- * @return string from property value, or NULL if there is no such property
+ * Return: string from property value, or NULL if there is no such property
  */
 const char *ofnode_read_string(ofnode node, const char *propname);
 
@@ -357,7 +360,7 @@ const char *ofnode_read_string(ofnode node, const char *propname);
  * @propname:	name of the property to read
  * @out_values:	pointer to return value, modified only if return value is 0
  * @sz:		number of array elements to read
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  *
  * 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,
@@ -374,7 +377,7 @@ int ofnode_read_u32_array(ofnode node, const char *propname,
  *
  * @node:	valid node reference to read property from
  * @propname:	name of property to read
- * @return true if property is present (meaning true), false if not present
+ * Return: true if property is present (meaning true), false if not present
  */
 bool ofnode_read_bool(ofnode node, const char *propname);
 
@@ -383,7 +386,7 @@ bool ofnode_read_bool(ofnode node, const char *propname);
  *
  * @node:	valid reference to parent node
  * @subnode_name: name of subnode to find
- * @return reference to subnode (which can be invalid if there is no such
+ * Return: reference to subnode (which can be invalid if there is no such
  * subnode)
  */
 ofnode ofnode_find_subnode(ofnode node, const char *subnode_name);
@@ -429,7 +432,7 @@ static inline ofnode ofnode_next_subnode(ofnode node)
  * by default.
  *
  * @node: node to examine
- * @return false (not enabled) or true (enabled)
+ * Return: false (not enabled) or true (enabled)
  */
 bool ofnode_is_enabled(ofnode node);
 
@@ -437,7 +440,7 @@ bool ofnode_is_enabled(ofnode node);
  * ofnode_first_subnode() - find the first subnode of a parent node
  *
  * @node:	valid reference to a valid parent node
- * @return reference to the first subnode (which can be invalid if the parent
+ * Return: reference to the first subnode (which can be invalid if the parent
  * node has no subnodes)
  */
 ofnode ofnode_first_subnode(ofnode node);
@@ -446,7 +449,7 @@ ofnode ofnode_first_subnode(ofnode node);
  * ofnode_next_subnode() - find the next sibling of a subnode
  *
  * @node:	valid reference to previous node (sibling)
- * @return reference to the next subnode (which can be invalid if the node
+ * Return: reference to the next subnode (which can be invalid if the node
  * has no more siblings)
  */
 ofnode ofnode_next_subnode(ofnode node);
@@ -456,7 +459,7 @@ ofnode ofnode_next_subnode(ofnode node);
  * ofnode_get_parent() - get the ofnode's parent (enclosing ofnode)
  *
  * @node: valid node to look up
- * @return ofnode reference of the parent node
+ * Return: ofnode reference of the parent node
  */
 ofnode ofnode_get_parent(ofnode node);
 
@@ -464,7 +467,7 @@ ofnode ofnode_get_parent(ofnode node);
  * ofnode_get_name() - get the name of a node
  *
  * @node: valid node to look up
- * @return name of node
+ * Return: name of node
  */
 const char *ofnode_get_name(ofnode node);
 
@@ -474,7 +477,7 @@ const char *ofnode_get_name(ofnode node);
  * @node: valid node to look up
  * @buf: buffer to write the node path into
  * @buflen: buffer size
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int ofnode_get_path(ofnode node, char *buf, int buflen);
 
@@ -482,7 +485,7 @@ int ofnode_get_path(ofnode node, char *buf, int buflen);
  * ofnode_get_by_phandle() - get ofnode from phandle
  *
  * @phandle:	phandle to look up
- * @return ofnode reference to the phandle
+ * Return: ofnode reference to the phandle
  */
 ofnode ofnode_get_by_phandle(uint phandle);
 
@@ -491,7 +494,7 @@ ofnode ofnode_get_by_phandle(uint phandle);
  *
  * @node: node to check
  * @propname: property to check
- * @return size of property if present, or -EINVAL if not
+ * Return: size of property if present, or -EINVAL if not
  */
 int ofnode_read_size(ofnode node, const char *propname);
 
@@ -504,7 +507,7 @@ int ofnode_read_size(ofnode node, const char *propname);
  * @node: node to read from
  * @index: Index of address to read (0 for first)
  * @size: Pointer to size of the address
- * @return address, or FDT_ADDR_T_NONE if not present or invalid
+ * Return: address, or FDT_ADDR_T_NONE if not present or invalid
  */
 phys_addr_t ofnode_get_addr_size_index(ofnode node, int index,
 				       fdt_size_t *size);
@@ -521,7 +524,7 @@ phys_addr_t ofnode_get_addr_size_index(ofnode node, int index,
  * @node: node to read from
  * @index: Index of address to read (0 for first)
  * @size: Pointer to size of the address
- * @return address, or FDT_ADDR_T_NONE if not present or invalid
+ * Return: address, or FDT_ADDR_T_NONE if not present or invalid
  */
 phys_addr_t ofnode_get_addr_size_index_notrans(ofnode node, int index,
 					       fdt_size_t *size);
@@ -533,7 +536,7 @@ phys_addr_t ofnode_get_addr_size_index_notrans(ofnode node, int index,
  *
  * @node: node to read from
  * @index: Index of address to read (0 for first)
- * @return address, or FDT_ADDR_T_NONE if not present or invalid
+ * Return: address, or FDT_ADDR_T_NONE if not present or invalid
  */
 phys_addr_t ofnode_get_addr_index(ofnode node, int index);
 
@@ -543,7 +546,7 @@ phys_addr_t ofnode_get_addr_index(ofnode node, int index);
  * This reads the register address from a node
  *
  * @node: node to read from
- * @return address, or FDT_ADDR_T_NONE if not present or invalid
+ * Return: address, or FDT_ADDR_T_NONE if not present or invalid
  */
 phys_addr_t ofnode_get_addr(ofnode node);
 
@@ -553,7 +556,7 @@ phys_addr_t ofnode_get_addr(ofnode node);
  * This reads the register size from a node
  *
  * @node: node to read from
- * @return size of the address, or FDT_SIZE_T_NONE if not present or invalid
+ * Return: size of the address, or FDT_SIZE_T_NONE if not present or invalid
  */
 fdt_size_t ofnode_get_size(ofnode node);
 
@@ -570,7 +573,7 @@ fdt_size_t ofnode_get_size(ofnode node);
  * @propname: name of the property containing the string list
  * @string: string to look up in the string list
  *
- * @return:
+ * Return:
  *   the index of the string in the list of strings
  *   -ENODATA if the property is not found
  *   -EINVAL on some other error
@@ -591,9 +594,9 @@ int ofnode_stringlist_search(ofnode node, const char *propname,
  * @node: node to check
  * @propname: name of the property containing the string list
  * @index: index of the string to return (cannot be negative)
- * @lenp: return location for the string length or an error code on failure
+ * @outp: return location for the string
  *
- * @return:
+ * Return:
  *   0 if found or -ve error value if not found
  */
 int ofnode_read_string_index(ofnode node, const char *propname, int index,
@@ -603,8 +606,8 @@ int ofnode_read_string_index(ofnode node, const char *propname, int index,
  * ofnode_read_string_count() - find the number of strings in a string list
  *
  * @node: node to check
- * @propname: name of the property containing the string list
- * @return:
+ * @property: name of the property containing the string list
+ * Return:
  *   number of strings in the list, or -ve error value if not found
  */
 int ofnode_read_string_count(ofnode node, const char *property);
@@ -620,11 +623,12 @@ int ofnode_read_string_count(ofnode node, const char *property);
  * changed as they point directly into the devicetree property.
  *
  * @node: node to check
+ * @property: name of the property containing the string list
  * @listp: returns an allocated, NULL-terminated list of strings if the return
  *	value is > 0, else is set to NULL
- * @return number of strings in list, 0 if none, -ENOMEM if out of memory,
- *	-EINVAL if no such property, -EENODATA if property is empty
- * @return: NULL-terminated list of strings (NULL if no property or empty)
+ * Return:
+ * number of strings in list, 0 if none, -ENOMEM if out of memory,
+ * -EINVAL if no such property, -EENODATA if property is empty
  */
 int ofnode_read_string_list(ofnode node, const char *property,
 			    const char ***listp);
@@ -639,19 +643,17 @@ int ofnode_read_string_list(ofnode node, const char *property,
  * Caller is responsible to call of_node_put() on the returned out_args->np
  * pointer.
  *
- * Example:
+ * Example: ::
  *
- * phandle1: node1 {
- *	#list-cells = <2>;
- * }
- *
- * phandle2: node2 {
- *	#list-cells = <1>;
- * }
- *
- * node3 {
- *	list = <&phandle1 1 2 &phandle2 3>;
- * }
+ *   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:
  * ofnode_parse_phandle_with_args(node3, "list", "#list-cells", 0, 1, &args);
@@ -659,13 +661,14 @@ int ofnode_read_string_list(ofnode node, const char *property,
  * @node:	device tree node containing a list
  * @list_name:	property name that contains a list
  * @cells_name:	property name that specifies phandles' arguments count
- * @cells_count: Cell count to use if @cells_name is NULL
+ * @cell_count: Cell count to use if @cells_name is NULL
  * @index:	index of a phandle to parse out
  * @out_args:	optional pointer to output arguments structure (will be filled)
- * @return 0 on success (with @out_args filled out if not NULL), -ENOENT if
- *	@list_name does not exist, -EINVAL if a phandle was not found,
- *	@cells_name could not be found, the arguments were truncated or there
- *	were too many arguments.
+ * Return:
+ *   0 on success (with @out_args filled out if not NULL), -ENOENT if
+ *   @list_name does not exist, -EINVAL if a phandle was not found,
+ *   @cells_name could not be found, the arguments were truncated or there
+ *   were too many arguments.
  */
 int ofnode_parse_phandle_with_args(ofnode node, const char *list_name,
 				   const char *cells_name, int cell_count,
@@ -682,10 +685,10 @@ int ofnode_parse_phandle_with_args(ofnode node, const char *list_name,
  * @node:	device tree node containing a list
  * @list_name:	property name that contains a list
  * @cells_name:	property name that specifies phandles' arguments count
- * @cells_count: Cell count to use if @cells_name is NULL
- * @return number of phandle on success, -ENOENT if @list_name does not
- *      exist, -EINVAL if a phandle was not found, @cells_name could not
- *      be found.
+ * @cell_count: Cell count to use if @cells_name is NULL
+ * Return:
+ *   number of phandle on success, -ENOENT if @list_name does not exist,
+ *   -EINVAL if a phandle was not found, @cells_name could not be found.
  */
 int ofnode_count_phandle_with_args(ofnode node, const char *list_name,
 				   const char *cells_name, int cell_count);
@@ -694,7 +697,7 @@ int ofnode_count_phandle_with_args(ofnode node, const char *list_name,
  * ofnode_path() - find a node by full path
  *
  * @path: Full path to node, e.g. "/bus/spi@1"
- * @return reference to the node found. Use ofnode_valid() to check if it exists
+ * Return: reference to the node found. Use ofnode_valid() to check if it exists
  */
 ofnode ofnode_path(const char *path);
 
@@ -704,9 +707,9 @@ ofnode ofnode_path(const char *path);
  * This looks for a property within the /chosen node and returns its value
  *
  * @propname: Property name to look for
- * @sizep: Returns size of property, or FDT_ERR_... error code if function
+ * @sizep: Returns size of property, or  `FDT_ERR_...` error code if function
  *	returns NULL
- * @return property value if found, else NULL
+ * Return: property value if found, else NULL
  */
 const void *ofnode_read_chosen_prop(const char *propname, int *sizep);
 
@@ -717,7 +720,7 @@ const void *ofnode_read_chosen_prop(const char *propname, int *sizep);
  * checking that it is a valid nul-terminated string
  *
  * @propname: Property name to look for
- * @return string value if found, else NULL
+ * Return: string value if found, else NULL
  */
 const char *ofnode_read_chosen_string(const char *propname);
 
@@ -727,7 +730,8 @@ const char *ofnode_read_chosen_string(const char *propname);
  * This looks up a named property in the chosen node and uses that as a path to
  * look up a code.
  *
- * @return the referenced node if present, else ofnode_null()
+ * @propname: Property name to look for
+ * Return: the referenced node if present, else ofnode_null()
  */
 ofnode ofnode_get_chosen_node(const char *propname);
 
@@ -737,9 +741,9 @@ ofnode ofnode_get_chosen_node(const char *propname);
  * This looks for a property within the /aliases node and returns its value
  *
  * @propname: Property name to look for
- * @sizep: Returns size of property, or FDT_ERR_... error code if function
+ * @sizep: Returns size of property, or `FDT_ERR_...` error code if function
  *	returns NULL
- * @return property value if found, else NULL
+ * Return: property value if found, else NULL
  */
 const void *ofnode_read_aliases_prop(const char *propname, int *sizep);
 
@@ -749,7 +753,8 @@ const void *ofnode_read_aliases_prop(const char *propname, int *sizep);
  * This looks up a named property in the aliases node and uses that as a path to
  * look up a code.
  *
- * @return the referenced node if present, else ofnode_null()
+ * @propname: Property name to look for
+ * Return: the referenced node if present, else ofnode_null()
  */
 ofnode ofnode_get_aliases_node(const char *propname);
 
@@ -761,10 +766,10 @@ struct display_timing;
  * See doc/device-tree-bindings/video/display-timing.txt for binding
  * information.
  *
- * @node	'display-timing' node containing the timing subnodes
- * @index	Index number to read (0=first timing subnode)
- * @config	Place to put timings
- * @return 0 if OK, -FDT_ERR_NOTFOUND if not found
+ * @node:	'display-timing' node containing the timing subnodes
+ * @index:	Index number to read (0=first timing subnode)
+ * @config:	Place to put timings
+ * Return: 0 if OK, -FDT_ERR_NOTFOUND if not found
  */
 int ofnode_decode_display_timing(ofnode node, int index,
 				 struct display_timing *config);
@@ -775,7 +780,7 @@ int ofnode_decode_display_timing(ofnode node, int index,
  * @node: node to read
  * @propname: property to read
  * @lenp: place to put length on success
- * @return pointer to property, or NULL if not found
+ * Return: pointer to property, or NULL if not found
  */
 const void *ofnode_get_property(ofnode node, const char *propname, int *lenp);
 
@@ -787,7 +792,7 @@ const void *ofnode_get_property(ofnode node, const char *propname, int *lenp);
  *
  * @node: node to read
  * @prop: place to put argument reference
- * @return 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
+ * Return: 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
  */
 int ofnode_get_first_property(ofnode node, struct ofprop *prop);
 
@@ -798,7 +803,7 @@ int ofnode_get_first_property(ofnode node, struct ofprop *prop);
  * and read all the property with ofnode_get_property_by_prop().
  *
  * @prop: reference of current argument and place to put reference of next one
- * @return 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
+ * Return: 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
  */
 int ofnode_get_next_property(struct ofprop *prop);
 
@@ -810,7 +815,7 @@ int ofnode_get_next_property(struct ofprop *prop);
  * @prop: reference on property
  * @propname: If non-NULL, place to property name on success,
  * @lenp: If non-NULL, place to put length on success
- * @return 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
+ * Return: 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
  */
 const void *ofnode_get_property_by_prop(const struct ofprop *prop,
 					const char **propname, int *lenp);
@@ -819,7 +824,7 @@ const void *ofnode_get_property_by_prop(const struct ofprop *prop,
  * ofnode_is_available() - check if a node is marked available
  *
  * @node: node to check
- * @return true if node's 'status' property is "okay" (or is missing)
+ * Return: true if node's 'status' property is "okay" (or is missing)
  */
 bool ofnode_is_available(ofnode node);
 
@@ -832,7 +837,7 @@ bool ofnode_is_available(ofnode node);
  * @node: node to read from
  * @propname: property to read
  * @sizep: place to put size value (on success)
- * @return address value, or FDT_ADDR_T_NONE on error
+ * Return: address value, or FDT_ADDR_T_NONE on error
  */
 phys_addr_t ofnode_get_addr_size(ofnode node, const char *propname,
 				 phys_size_t *sizep);
@@ -845,11 +850,12 @@ phys_addr_t ofnode_get_addr_size(ofnode node, const char *propname,
  * for the array (count bytes). It may have more, but this will be ignored.
  * The data is not copied.
  *
- * @node	node to examine
- * @propname	name of property to find
- * @sz		number of array elements
- * @return pointer to byte array if found, or NULL if the property is not
- *		found or there is not enough data
+ * @node:	node to examine
+ * @propname:	name of property to find
+ * @sz:		number of array elements
+ * Return:
+ * pointer to byte array if found, or NULL if the property is not found or
+ * there is not enough data
  */
 const uint8_t *ofnode_read_u8_array_ptr(ofnode node, const char *propname,
 					size_t sz);
@@ -861,13 +867,14 @@ const uint8_t *ofnode_read_u8_array_ptr(ofnode node, const char *propname,
  * corresponds to the given type in the form of fdt_pci_addr.
  * The property must hold one fdt_pci_addr with a lengh.
  *
- * @node	node to examine
- * @type	pci address type (FDT_PCI_SPACE_xxx)
- * @propname	name of property to find
- * @addr	returns pci address in the form of fdt_pci_addr
- * @return 0 if ok, -ENOENT if the property did not exist, -EINVAL if the
- *		format of the property was invalid, -ENXIO if the requested
- *		address type was not found
+ * @node:	node to examine
+ * @type:	pci address type (FDT_PCI_SPACE_xxx)
+ * @propname:	name of property to find
+ * @addr:	returns pci address in the form of fdt_pci_addr
+ * Return:
+ * 0 if ok, -ENOENT if the property did not exist, -EINVAL if the
+ * format of the property was invalid, -ENXIO if the requested
+ * address type was not found
  */
 int ofnode_read_pci_addr(ofnode node, enum fdt_pci_space type,
 			 const char *propname, struct fdt_pci_addr *addr);
@@ -878,10 +885,10 @@ int ofnode_read_pci_addr(ofnode node, enum fdt_pci_space type,
  * Look at the compatible property of a device node that represents a PCI
  * device and extract pci vendor id and device id from it.
  *
- * @param node		node to examine
- * @param vendor	vendor id of the pci device
- * @param device	device id of the pci device
- * @return 0 if ok, negative on error
+ * @node:	node to examine
+ * @vendor:	vendor id of the pci device
+ * @device:	device id of the pci device
+ * Return: 0 if ok, negative on error
  */
 int ofnode_read_pci_vendev(ofnode node, u16 *vendor, u16 *device);
 
@@ -892,7 +899,7 @@ int ofnode_read_pci_vendev(ofnode node, u16 *vendor, u16 *device);
  * which controls the given node.
  *
  * @node: Node to check
- * @return number of address cells this node uses
+ * Return: number of address cells this node uses
  */
 int ofnode_read_addr_cells(ofnode node);
 
@@ -903,7 +910,7 @@ int ofnode_read_addr_cells(ofnode node);
  * which controls the given node.
  *
  * @node: Node to check
- * @return number of size cells this node uses
+ * Return: number of size cells this node uses
  */
 int ofnode_read_size_cells(ofnode node);
 
@@ -912,8 +919,8 @@ int ofnode_read_size_cells(ofnode node);
  *
  * This function matches fdt_address_cells().
  *
- * @np: Node pointer to check
- * @return value of #address-cells property in this node, or 2 if none
+ * @node: Node to check
+ * Return: value of #address-cells property in this node, or 2 if none
  */
 int ofnode_read_simple_addr_cells(ofnode node);
 
@@ -922,8 +929,8 @@ int ofnode_read_simple_addr_cells(ofnode node);
  *
  * This function matches fdt_size_cells().
  *
- * @np: Node pointer to check
- * @return value of #size-cells property in this node, or 2 if none
+ * @node: Node to check
+ * Return: value of #size-cells property in this node, or 2 if none
  */
 int ofnode_read_simple_size_cells(ofnode node);
 
@@ -942,14 +949,13 @@ int ofnode_read_simple_size_cells(ofnode node);
  * There are 4 settings currently in use
  * - u-boot,dm-pre-proper: U-Boot proper pre-relocation only
  * - u-boot,dm-pre-reloc: legacy and indicates any of TPL or SPL
- *   Existing platforms only use it to indicate nodes needed in
- *   SPL. Should probably be replaced by u-boot,dm-spl for
- *   new platforms.
+ * Existing platforms only use it to indicate nodes needed in
+ * SPL. Should probably be replaced by u-boot,dm-spl for new platforms.
  * - u-boot,dm-spl: SPL and U-Boot pre-relocation
  * - u-boot,dm-tpl: TPL and U-Boot pre-relocation
  *
  * @node: node to check
- * @return true if node is needed in SPL/TL, false otherwise
+ * Return: true if node is needed in SPL/TL, false otherwise
  */
 bool ofnode_pre_reloc(ofnode node);
 
@@ -961,7 +967,7 @@ bool ofnode_pre_reloc(ofnode node);
  * @node: Node to read from
  * @index: Index of resource to read (0 = first)
  * @res: Returns resource that was read, on success
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int ofnode_read_resource(ofnode node, uint index, struct resource *res);
 
@@ -975,7 +981,7 @@ int ofnode_read_resource(ofnode node, uint index, struct resource *res);
  * @node: Node to read from
  * @name: Name of resource to read
  * @res: Returns resource that was read, on success
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int ofnode_read_resource_byname(ofnode node, const char *name,
 				struct resource *res);
@@ -987,7 +993,7 @@ int ofnode_read_resource_byname(ofnode node, const char *name,
  *
  * @from: ofnode to start from (use ofnode_null() to start at the beginning)
  * @compat: Compatible string to match
- * @return ofnode found, or ofnode_null() if none
+ * Return: ofnode found, or ofnode_null() if none
  */
 ofnode ofnode_by_compatible(ofnode from, const char *compat);
 
@@ -998,9 +1004,11 @@ ofnode ofnode_by_compatible(ofnode from, const char *compat);
  * @propval and a length @proplen.
  *
  * @from: ofnode to start from (use ofnode_null() to start at the
- * beginning) @propname: property name to check @propval: property value to
- * search for @proplen: length of the value in propval @return ofnode
- * found, or ofnode_null() if none
+ * beginning)
+ * @propname: property name to check
+ * @propval: property value to search for
+ * @proplen: length of the value in propval
+ * Return: ofnode found, or ofnode_null() if none
  */
 ofnode ofnode_by_prop_value(ofnode from, const char *propname,
 			    const void *propval, int proplen);
@@ -1011,14 +1019,13 @@ ofnode ofnode_by_prop_value(ofnode from, const char *propname,
  * @node:       child node (ofnode, lvalue)
  * @parent:     parent node (ofnode)
  *
- * This is a wrapper around a for loop and is used like so:
+ * This is a wrapper around a for loop and is used like so: ::
  *
- *	ofnode node;
- *
- *	ofnode_for_each_subnode(node, parent) {
- *		Use node
- *		...
- *	}
+ *   ofnode node;
+ *   ofnode_for_each_subnode(node, parent) {
+ *       Use node
+ *       ...
+ *   }
  *
  * Note that this is implemented as a macro and @node is used as
  * iterator in the loop. The parent variable can be a constant or even a
@@ -1036,14 +1043,13 @@ ofnode ofnode_by_prop_value(ofnode from, const char *propname,
  * @node:       child node (ofnode, lvalue)
  * @compat:     compatible string to match
  *
- * This is a wrapper around a for loop and is used like so:
- *
- *	ofnode node;
+ * This is a wrapper around a for loop and is used like so: ::
  *
- *	ofnode_for_each_compatible_node(node, parent, compatible) {
- *		Use node
- *		...
- *	}
+ *   ofnode node;
+ *   ofnode_for_each_compatible_node(node, parent, compatible) {
+ *      Use node
+ *      ...
+ *   }
  *
  * Note that this is implemented as a macro and @node is used as
  * iterator in the loop.
@@ -1056,8 +1062,8 @@ ofnode ofnode_by_prop_value(ofnode from, const char *propname,
 /**
  * ofnode_get_child_count() - get the child count of a ofnode
  *
- * @node: valid node to get its child count
- * @return the number of subnodes
+ * @parent: valid node to get its child count
+ * Return: the number of subnodes
  */
 int ofnode_get_child_count(ofnode parent);
 
@@ -1068,10 +1074,9 @@ int ofnode_get_child_count(ofnode parent);
  * function walks up the tree and applies the various bus mappings along the
  * way.
  *
- * @ofnode: Device tree node giving the context in which to translate the
- *          address
+ * @node: Device tree node giving the context in which to translate the address
  * @in_addr: pointer to the address to translate
- * @return the translated address; OF_BAD_ADDR on error
+ * Return: the translated address; OF_BAD_ADDR on error
  */
 u64 ofnode_translate_address(ofnode node, const fdt32_t *in_addr);
 
@@ -1082,10 +1087,10 @@ u64 ofnode_translate_address(ofnode node, const fdt32_t *in_addr);
  * This function walks up the tree and applies the various bus mappings along
  * the way.
  *
- * @ofnode: Device tree node giving the context in which to translate the
- *          DMA address
+ * @node: Device tree node giving the context in which to translate the
+ *        DMA address
  * @in_addr: pointer to the DMA address to translate
- * @return the translated DMA address; OF_BAD_ADDR on error
+ * Return: the translated DMA address; OF_BAD_ADDR on error
  */
 u64 ofnode_translate_dma_address(ofnode node, const fdt32_t *in_addr);
 
@@ -1095,12 +1100,11 @@ u64 ofnode_translate_dma_address(ofnode node, const fdt32_t *in_addr);
  * Get DMA ranges for a specifc node, this is useful to perform bus->cpu and
  * cpu->bus address translations
  *
- * @param blob		Pointer to device tree blob
- * @param node_offset	Node DT offset
- * @param cpu		Pointer to variable storing the range's cpu address
- * @param bus		Pointer to variable storing the range's bus address
- * @param size		Pointer to variable storing the range's size
- * @return translated DMA address or OF_BAD_ADDR on error
+ * @node: Device tree node
+ * @cpu: Pointer to variable storing the range's cpu address
+ * @bus: Pointer to variable storing the range's bus address
+ * @size: Pointer to variable storing the range's size
+ * Return: translated DMA address or OF_BAD_ADDR on error
  */
 int ofnode_get_dma_range(ofnode node, phys_addr_t *cpu, dma_addr_t *bus,
 			 u64 *size);
@@ -1112,7 +1116,7 @@ int ofnode_get_dma_range(ofnode node, phys_addr_t *cpu, dma_addr_t *bus,
  *
  * @node:	Device tree node for which compatible needs to be verified.
  * @compat:	Compatible string which needs to verified in the given node.
- * @return true if OK, false if the compatible is not found
+ * Return: true if OK, false if the compatible is not found
  */
 int ofnode_device_is_compatible(ofnode node, const char *compat);
 
@@ -1127,7 +1131,7 @@ int ofnode_device_is_compatible(ofnode node, const char *compat);
  * @len:	The length of the new value of the property
  * @value:	The new value of the property (must be valid prior to calling
  *		the function)
- * @return 0 if successful, -ve on error
+ * Return: 0 if successful, -ve on error
  */
 int ofnode_write_prop(ofnode node, const char *propname, int len,
 		      const void *value);
@@ -1142,7 +1146,7 @@ int ofnode_write_prop(ofnode node, const char *propname, int len,
  * @propname:	The name of the string property to set
  * @value:	The new value of the string property (must be valid prior to
  *		calling the function)
- * @return 0 if successful, -ve on error
+ * Return: 0 if successful, -ve on error
  */
 int ofnode_write_string(ofnode node, const char *propname, const char *value);
 
@@ -1157,7 +1161,7 @@ int ofnode_write_string(ofnode node, const char *propname, const char *value);
  * @node:	The node to enable
  * @value:	Flag that tells the function to either disable or enable the
  *		node
- * @return 0 if successful, -ve on error
+ * Return: 0 if successful, -ve on error
  */
 int ofnode_set_enabled(ofnode node, bool value);
 
@@ -1168,8 +1172,8 @@ int ofnode_set_enabled(ofnode node, bool value);
  *
  * See doc/config.txt for bindings
  *
- * @prop_name	property name to look up
- * @return true, if it exists, false if not
+ * @prop_name:	property name to look up
+ * Return: true, if it exists, false if not
  */
 bool ofnode_conf_read_bool(const char *prop_name);
 
@@ -1182,7 +1186,7 @@ bool ofnode_conf_read_bool(const char *prop_name);
  *
  * @prop_name: property name to look up
  * @default_val: default value to return if the property is not found
- * @return integer value, if found, or @default_val if not
+ * Return: integer value, if found, or @default_val if not
  */
 int ofnode_conf_read_int(const char *prop_name, int default_val);
 
@@ -1194,7 +1198,7 @@ int ofnode_conf_read_int(const char *prop_name, int default_val);
  * See doc/config.txt for bindings
  *
  * @prop_name: property name to look up
- * @return string value, if found, or NULL if not
+ * Return: string value, if found, or NULL if not
  */
 const char *ofnode_conf_read_str(const char *prop_name);
 
-- 
2.25.1

Re: [PATCH 1/9] doc: add include/dm/uclass.h to the HTML documentation

[Heinrich Schuchardt]

On 1/12/22 10:53, Patrick Delaunay wrote:
> Correct Sphinx style comments in include/dm/uclass.h
> and add the driver model UCLASS API to the HTML documentation.
>
> Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
> ---
>
>   doc/api/dm.rst      |  9 ++++++
>   doc/api/index.rst   |  1 +
>   include/dm/uclass.h | 75 ++++++++++++++++++++++-----------------------
>   3 files changed, 47 insertions(+), 38 deletions(-)
>   create mode 100644 doc/api/dm.rst
>
> diff --git a/doc/api/dm.rst b/doc/api/dm.rst
> new file mode 100644
> index 0000000000..edce25da51
> --- /dev/null
> +++ b/doc/api/dm.rst
> @@ -0,0 +1,9 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +Driver Model
> +============
> +
> +Uclass and Driver
> +-----------------
> +
> +.. kernel-doc:: include/dm/uclass.h
> diff --git a/doc/api/index.rst b/doc/api/index.rst
> index 806c7385a6..3f36174167 100644
> --- a/doc/api/index.rst
> +++ b/doc/api/index.rst
> @@ -7,6 +7,7 @@ U-Boot API documentation
>      :maxdepth: 2
>
>      dfu
> +   dm
>      efi
>      getopt
>      linker_lists
> diff --git a/include/dm/uclass.h b/include/dm/uclass.h
> index f1fd2ba246..a12a872d94 100644
> --- a/include/dm/uclass.h
> +++ b/include/dm/uclass.h
> @@ -84,7 +84,7 @@ struct udevice;
>    * its children. If non-zero this is the size of this data, to be allocated
>    * in the child device's parent_plat pointer. This value is only used as
>    * a fallback if this member is 0 in the driver.
> - * @flags: Flags for this uclass (DM_UC_...)
> + * @flags: Flags for this uclass ``(DM_UC_...)``
>    */
>   struct uclass_driver {
>   	const char *name;
> @@ -127,17 +127,16 @@ struct uclass_driver {
>    * build time. Before this is used, an extern UCLASS_DRIVER() must have been
>    * declared.
>    *
> - * For example:
> + * For example: ::

Nits:
"For example::" has the same effect. I will change this when merging.

Reviewed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>

>    *
> - * extern UCLASS_DRIVER(clk);
> - *
> - * struct uclass_driver *drvs[] = {
> - *	DM_UCLASS_DRIVER_REF(clk),
> - * };
> + *   extern UCLASS_DRIVER(clk);
> + *   struct uclass_driver *drvs[] = {
> + *       DM_UCLASS_DRIVER_REF(clk),
> + *   };
>    *
>    * @_name: Name of the uclass_driver. This must be a valid C identifier, used by
>    *	the linker_list.
> - * @returns struct uclass_driver * for the uclass driver
> + * Return: struct uclass_driver * for the uclass driver
>    */
>   #define DM_UCLASS_DRIVER_REF(_name)					\
>   	ll_entry_ref(struct uclass_driver, _name, uclass_driver)
> @@ -145,8 +144,8 @@ struct uclass_driver {
>   /**
>    * uclass_get_priv() - Get the private data for a uclass
>    *
> - * @uc		Uclass to check
> - * @return private data, or NULL if none
> + * @uc:	Uclass to check
> + * Return: private data, or NULL if none
>    */
>   void *uclass_get_priv(const struct uclass *uc);
>
> @@ -159,8 +158,8 @@ void *uclass_get_priv(const struct uclass *uc);
>    *
>    * @key: ID to look up
>    * @ucp: Returns pointer to uclass (there is only one per ID)
> - * @return 0 if OK, -EDEADLK if driver model is not yet inited, other -ve on
> - *	other error
> + * Return: 0 if OK, -EDEADLK if driver model is not yet inited, other -ve on
> + * other error
>    */
>   int uclass_get(enum uclass_id key, struct uclass **ucp);
>
> @@ -168,16 +167,16 @@ int uclass_get(enum uclass_id key, struct uclass **ucp);
>    * uclass_get_name() - Get the name of a uclass driver
>    *
>    * @id: ID to look up
> - * @returns the name of the uclass driver for that ID, or NULL if none
> + * Return: the name of the uclass driver for that ID, or NULL if none
>    */
>   const char *uclass_get_name(enum uclass_id id);
>
>   /**
> - * uclass_get_by_name() - Look up a uclass by its driver name
> + * uclass_get_by_name_len() - Look up a uclass by its partial driver name
>    *
>    * @name: Name to look up
> - * @len: Length of name
> - * @returns the associated uclass ID, or UCLASS_INVALID if not found
> + * @len: Length of the partial name
> + * Return: the associated uclass ID, or UCLASS_INVALID if not found
>    */
>   enum uclass_id uclass_get_by_name_len(const char *name, int len);
>
> @@ -185,7 +184,7 @@ enum uclass_id uclass_get_by_name_len(const char *name, int len);
>    * uclass_get_by_name() - Look up a uclass by its driver name
>    *
>    * @name: Name to look up
> - * @returns the associated uclass ID, or UCLASS_INVALID if not found
> + * Return: the associated uclass ID, or UCLASS_INVALID if not found
>    */
>   enum uclass_id uclass_get_by_name(const char *name);
>
> @@ -197,7 +196,7 @@ enum uclass_id uclass_get_by_name(const char *name);
>    * @id: ID to look up
>    * @index: Device number within that uclass (0=first)
>    * @devp: Returns pointer to device (there is only one per for each ID)
> - * @return 0 if OK, -ve on error
> + * Return: 0 if OK, -ve on error
>    */
>   int uclass_get_device(enum uclass_id id, int index, struct udevice **devp);
>
> @@ -211,7 +210,7 @@ int uclass_get_device(enum uclass_id id, int index, struct udevice **devp);
>    * @id: ID to look up
>    * @name: name of a device to get
>    * @devp: Returns pointer to device (the first one with the name)
> - * @return 0 if OK, -ve on error
> + * Return: 0 if OK, -ve on error
>    */
>   int uclass_get_device_by_name(enum uclass_id id, const char *name,
>   			      struct udevice **devp);
> @@ -228,7 +227,7 @@ int uclass_get_device_by_name(enum uclass_id id, const char *name,
>    * @id: ID to look up
>    * @seq: Sequence number to find (0=first)
>    * @devp: Returns pointer to device (there is only one for each seq)
> - * @return 0 if OK, -ve on error
> + * Return: 0 if OK, -ve on error
>    */
>   int uclass_get_device_by_seq(enum uclass_id id, int seq, struct udevice **devp);
>
> @@ -243,7 +242,7 @@ int uclass_get_device_by_seq(enum uclass_id id, int seq, struct udevice **devp);
>    * @id: ID to look up
>    * @node: Device tree offset to search for (if -ve then -ENODEV is returned)
>    * @devp: Returns pointer to device (there is only one for each node)
> - * @return 0 if OK, -ve on error
> + * Return: 0 if OK, -ve on error
>    */
>   int uclass_get_device_by_of_offset(enum uclass_id id, int node,
>   				   struct udevice **devp);
> @@ -257,9 +256,9 @@ int uclass_get_device_by_of_offset(enum uclass_id id, int node,
>    * The device is probed to activate it ready for use.
>    *
>    * @id: ID to look up
> - * @np: Device tree node to search for (if NULL then -ENODEV is returned)
> + * @node: Device tree node to search for (if NULL then -ENODEV is returned)
>    * @devp: Returns pointer to device (there is only one for each node)
> - * @return 0 if OK, -ve on error
> + * Return: 0 if OK, -ve on error
>    */
>   int uclass_get_device_by_ofnode(enum uclass_id id, ofnode node,
>   				struct udevice **devp);
> @@ -275,8 +274,8 @@ int uclass_get_device_by_ofnode(enum uclass_id id, ofnode node,
>    * @phandle_id: the phandle id to look up
>    * @devp: Returns pointer to device (there is only one for each node). NULL if
>    *	there is no such device.
> - * @return 0 if OK, -ENODEV if there is no device match the phandle, other
> - *	-ve on error
> + * Return: 0 if OK, -ENODEV if there is no device match the phandle, other
> + * -ve on error
>    */
>   int uclass_get_device_by_phandle_id(enum uclass_id id, uint phandle_id,
>   				    struct udevice **devp);
> @@ -292,8 +291,8 @@ int uclass_get_device_by_phandle_id(enum uclass_id id, uint phandle_id,
>    * @parent: Parent device containing the phandle pointer
>    * @name: Name of property in the parent device node
>    * @devp: Returns pointer to device (there is only one for each node)
> - * @return 0 if OK, -ENOENT if there is no @name present in the node, other
> - *	-ve on error
> + * Return: 0 if OK, -ENOENT if there is no @name present in the node, other
> + * -ve on error
>    */
>   int uclass_get_device_by_phandle(enum uclass_id id, struct udevice *parent,
>   				 const char *name, struct udevice **devp);
> @@ -310,7 +309,7 @@ int uclass_get_device_by_phandle(enum uclass_id id, struct udevice *parent,
>    * @id: ID to look up
>    * @drv: Driver to look for
>    * @devp: Returns pointer to the first device with that driver
> - * @return 0 if OK, -ve on error
> + * Return: 0 if OK, -ve on error
>    */
>   int uclass_get_device_by_driver(enum uclass_id id, const struct driver *drv,
>   				struct udevice **devp);
> @@ -327,7 +326,7 @@ int uclass_get_device_by_driver(enum uclass_id id, const struct driver *drv,
>    * @devp: Returns pointer to the first device in that uclass if no error
>    * occurred, or NULL if there is no first device, or an error occurred with
>    * that device.
> - * @return 0 if OK (found or not found), other -ve on error
> + * Return: 0 if OK (found or not found), other -ve on error
>    */
>   int uclass_first_device(enum uclass_id id, struct udevice **devp);
>
> @@ -338,7 +337,7 @@ int uclass_first_device(enum uclass_id id, struct udevice **devp);
>    *
>    * @id: Uclass ID to look up
>    * @devp: Returns pointer to the first device in that uclass, or NULL if none
> - * @return 0 if found, -ENODEV if not found, other -ve on error
> + * Return: 0 if found, -ENODEV if not found, other -ve on error
>    */
>   int uclass_first_device_err(enum uclass_id id, struct udevice **devp);
>
> @@ -353,7 +352,7 @@ int uclass_first_device_err(enum uclass_id id, struct udevice **devp);
>    * @devp: On entry, pointer to device to lookup. On exit, returns pointer
>    * to the next device in the uclass if no error occurred, or NULL if there is
>    * no next device, or an error occurred with that next device.
> - * @return 0 if OK (found or not found), other -ve on error
> + * Return: 0 if OK (found or not found), other -ve on error
>    */
>   int uclass_next_device(struct udevice **devp);
>
> @@ -365,7 +364,7 @@ int uclass_next_device(struct udevice **devp);
>    * @devp: On entry, pointer to device to lookup. On exit, returns pointer
>    * to the next device in the uclass if no error occurred, or NULL if
>    * there is no next device.
> - * @return 0 if found, -ENODEV if not found, other -ve on error
> + * Return: 0 if found, -ENODEV if not found, other -ve on error
>    */
>   int uclass_next_device_err(struct udevice **devp);
>
> @@ -380,7 +379,7 @@ int uclass_next_device_err(struct udevice **devp);
>    * @id: Uclass ID to look up
>    * @devp: Returns pointer to the first device in that uclass, or NULL if there
>    * is no first device
> - * @return 0 if OK (found or not found), other -ve on error. If an error occurs
> + * Return: 0 if OK (found or not found), other -ve on error. If an error occurs
>    * it is still possible to move to the next device.
>    */
>   int uclass_first_device_check(enum uclass_id id, struct udevice **devp);
> @@ -395,7 +394,7 @@ int uclass_first_device_check(enum uclass_id id, struct udevice **devp);
>    *
>    * @devp: On entry, pointer to device to lookup. On exit, returns pointer
>    * to the next device in the uclass if any
> - * @return 0 if OK (found or not found), other -ve on error. If an error occurs
> + * Return: 0 if OK (found or not found), other -ve on error. If an error occurs
>    * it is still possible to move to the next device.
>    */
>   int uclass_next_device_check(struct udevice **devp);
> @@ -409,7 +408,7 @@ int uclass_next_device_check(struct udevice **devp);
>    * @id: Uclass ID to check
>    * @driver_data: Driver data to search for
>    * @devp: Returns pointer to the first matching device in that uclass, if found
> - * @return 0 if found, -ENODEV if not found, other -ve on error
> + * Return: 0 if found, -ENODEV if not found, other -ve on error
>    */
>   int uclass_first_device_drvdata(enum uclass_id id, ulong driver_data,
>   				struct udevice **devp);
> @@ -421,7 +420,7 @@ int uclass_first_device_drvdata(enum uclass_id id, ulong driver_data,
>    * looking for its ID.
>    *
>    * @id: uclass ID to look up
> - * @return 0 if OK, other -ve on error
> + * Return: 0 if OK, other -ve on error
>    */
>   int uclass_probe_all(enum uclass_id id);
>
> @@ -429,7 +428,7 @@ int uclass_probe_all(enum uclass_id id);
>    * uclass_id_count() - Count the number of devices in a uclass
>    *
>    * @id: uclass ID to look up
> - * @return number of devices in that uclass (0 if none)
> + * Return: number of devices in that uclass (0 if none)
>    */
>   int uclass_id_count(enum uclass_id id);
>
> @@ -444,7 +443,7 @@ int uclass_id_count(enum uclass_id id);
>    * @id: enum uclass_id ID to use
>    * @pos: struct udevice * to hold the current device. Set to NULL when there
>    * are no more devices.
> - * @uc: temporary uclass variable (struct uclass *)
> + * @uc: temporary uclass variable (``struct uclass *``)
>    */
>   #define uclass_id_foreach_dev(id, pos, uc) \
>   	if (!uclass_get(id, &uc)) \

Re: [PATCH 2/9] doc: add include/dm/root.h to the HTML documentation

[Heinrich Schuchardt]

On 1/12/22 10:53, Patrick Delaunay wrote:
> Correct Sphinx style comments in include/dm/devres.h
> and add the associated driver model API to the HTML documentation.
>
> Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>

Reviewed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>

Re: [PATCH 5/9] doc: add include/dm/device.h to the HTML documentation

[Heinrich Schuchardt]

On 1/12/22 10:53, Patrick Delaunay wrote:
> Correct Sphinx style comments in include/dm/device.h
> and add the driver model device API to the HTML documentation.
>
> Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
> ---
>
>   doc/api/dm.rst      |   5 ++
>   include/dm/device.h | 209 ++++++++++++++++++++++++--------------------
>   2 files changed, 121 insertions(+), 93 deletions(-)
>
> diff --git a/doc/api/dm.rst b/doc/api/dm.rst
> index 6f72b0b620..7a77a91c1f 100644
> --- a/doc/api/dm.rst
> +++ b/doc/api/dm.rst
> @@ -10,3 +10,8 @@ Uclass and Driver
>   .. kernel-doc:: include/dm/root.h
>   .. kernel-doc:: include/dm/lists.h
>   .. kernel-doc:: include/dm/platdata.h
> +
> +Device
> +------
> +
> +.. kernel-doc:: include/dm/device.h
> diff --git a/include/dm/device.h b/include/dm/device.h
> index cf785f7ae2..bc8da72b50 100644
> --- a/include/dm/device.h
> +++ b/include/dm/device.h
> @@ -145,7 +145,7 @@ enum {
>    * @uclass_node: Used by uclass to link its devices
>    * @child_head: List of children of this device
>    * @sibling_node: Next device in list of all devices
> - * @flags_: Flags for this device DM_FLAG_... (do not access outside driver
> + * @flags_: Flags for this device `DM_FLAG_...` (do not access outside driver
>    *	model)
>    * @seq_: Allocated sequence number for this device (-1 = none). This is set up
>    * when the device is bound and is unique within the device's uclass. If the
> @@ -193,14 +193,14 @@ struct udevice {
>   };
>
>   /**
> - * udevice_rt - runtime information set up by U-Boot
> + * struct udevice_rt - runtime information set up by U-Boot
>    *
>    * This is only used with OF_PLATDATA_RT
>    *
>    * There is one of these for every udevice in the linker list, indexed by
>    * the udevice_info idx value.
>    *
> - * @flags_: Flags for this device DM_FLAG_... (do not access outside driver
> + * @flags_: Flags for this device `DM_FLAG_...` (do not access outside driver
>    *	model)
>    */
>   struct udevice_rt {
> @@ -239,7 +239,7 @@ static inline void dev_bic_flags(struct udevice *dev, u32 bic)
>    * dev_ofnode() - get the DT node reference associated with a udevice
>    *
>    * @dev:	device to check
> - * @return reference of the the device's DT node
> + * Return: reference of the device's DT node
>    */
>   static inline ofnode dev_ofnode(const struct udevice *dev)
>   {
> @@ -351,7 +351,7 @@ struct udevice_id {
>    * @ops: Driver-specific operations. This is typically a list of function
>    * pointers defined by the driver, to implement driver functions required by
>    * the uclass.
> - * @flags: driver flags - see DM_FLAGS_...
> + * @flags: driver flags - see `DM_FLAGS_...`
>    * @acpi_ops: Advanced Configuration and Power Interface (ACPI) operations,
>    * allowing the device to add things to the ACPI tables passed to Linux
>    */
> @@ -378,11 +378,24 @@ struct driver {
>   #endif
>   };
>
> -/* Declare a new U-Boot driver */
> +/**
> + * U_BOOT_DRIVER() - Declare a new U-Boot driver
> + * @__name: name of the driver
> + */
>   #define U_BOOT_DRIVER(__name)						\
>   	ll_entry_declare(struct driver, __name, driver)
>
> -/* Get a pointer to a given driver */
> +/**
> + * DM_DRIVER_GET() - Get a pointer to a given driver
> + *
> + * This is useful in code for referencing a driver at build time.
> + * Before this is used, an extern U_BOOT_DRIVER() must have been
> + * declared.
> + *
> + * @__name:	Name of the driver. This must be a valid C identifier,
> + * used by the linker_list
> + * Return: struct driver * for the driver
> + */
>   #define DM_DRIVER_GET(__name)						\
>   	ll_entry_get(struct driver, __name, driver)
>
> @@ -392,60 +405,69 @@ struct driver {
>    * This is useful in data structures and code for referencing a driver at
>    * build time. Before this is used, an extern U_BOOT_DRIVER() must have been
>    * declared.
> + * This is like DM_DRIVER_GET, but without the extra code, so it is suitable
> + * for putting into data structures.
>    *
> - * For example:
> - *
> - * extern U_BOOT_DRIVER(sandbox_fixed_clock);
> + * For example: ::
>    *
> - * struct driver *drvs[] = {
> - *	DM_DRIVER_REF(sandbox_fixed_clock),
> - * };
> + *   extern U_BOOT_DRIVER(sandbox_fixed_clock);
> + *   struct driver *drvs[] = {
> + *       DM_DRIVER_REF(sandbox_fixed_clock),
> + *   };
>    *
> - * @_name: Name of the driver. This must be a valid C identifier, used by the
> - *	linker_list
> - * @returns struct driver * for the driver
> + * @_name:	Name of the driver. This must be a valid C identifier,
> + * used by the linker_list
> + * Return: struct driver * for the driver
>    */
>   #define DM_DRIVER_REF(_name)					\
>   	ll_entry_ref(struct driver, _name, driver)
>
>   /**
> - * Declare a macro to state a alias for a driver name. This macro will

nits:
%s/a alias/an alias/

> - * produce no code but its information will be parsed by tools like
> - * dtoc
> + * DM_DRIVER_ALIAS() - Declare a macro to state a alias for a driver name
> + *
> + * This macro will produce no code but its information will be parsed by tools
> + * like dtoc
> + *
> + * @__name:	name of driver
> + * @__alias:	alias for the driver name
>    */
>   #define DM_DRIVER_ALIAS(__name, __alias)
>
>   /**
> - * Declare a macro to indicate which phase of U-Boot this driver is fore.
> - *
> + * DM_PHASE() - Declare a macro to indicate which phase of U-Boot this driver is fore.

%s/fore\./for/

Will correct when merging.

Reviewed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>

>    *
>    * This macro produces no code but its information will be parsed by dtoc. The
>    * macro can be only be used once in a driver. Put it within the U_BOOT_DRIVER()
> - * declaration, e.g.:
> + * declaration, e.g.: ::
> + *
> + *   U_BOOT_DRIVER(cpu) = {
> + *       .name = ...
> + *       ...
> + *       DM_PHASE(tpl)
> + *   };
>    *
> - * U_BOOT_DRIVER(cpu) = {
> - *	.name = ...
> - *	...
> - *	DM_PHASE(tpl)
> - * };
> + * @_phase:	Associated phase of U-Boot ("spl", "tpl")
>    */
>   #define DM_PHASE(_phase)
>
>   /**
> - * Declare a macro to declare a header needed for a driver. Often the correct
> - * header can be found automatically, but only for struct declarations. For
> - * enums and #defines used in the driver declaration and declared in a different
> - * header from the structs, this macro must be used.
> + * DM_HEADER() - Declare a macro to declare a header needed for a driver.
> + *
> + * Often the correct header can be found automatically, but only for struct
> + * declarations. For enums and #defines used in the driver declaration and
> + * declared in a different header from the structs, this macro must be used.
>    *
>    * This macro produces no code but its information will be parsed by dtoc. The
>    * macro can be used multiple times with different headers, for the same driver.
> - * Put it within the U_BOOT_DRIVER() declaration, e.g.:
> + * Put it within the U_BOOT_DRIVER() declaration, e.g.: ::
> + *
> + *   U_BOOT_DRIVER(cpu) = {
> + *       .name = ...
> + *       ...
> + *       DM_HEADER(<asm/cpu.h>)
> + *   };
>    *
> - * U_BOOT_DRIVER(cpu) = {
> - *	.name = ...
> - *	...
> - *	DM_HEADER(<asm/cpu.h>)
> - * };
> + * @_hdr:	header needed for a driver
>    */
>   #define DM_HEADER(_hdr)
>
> @@ -454,8 +476,8 @@ struct driver {
>    *
>    * This checks that dev is not NULL, but no other checks for now
>    *
> - * @dev		Device to check
> - * @return platform data, or NULL if none
> + * @dev:	Device to check
> + * Return: platform data, or NULL if none
>    */
>   void *dev_get_plat(const struct udevice *dev);
>
> @@ -464,8 +486,8 @@ void *dev_get_plat(const struct udevice *dev);
>    *
>    * This checks that dev is not NULL, but no other checks for now
>    *
> - * @dev		Device to check
> - * @return parent's platform data, or NULL if none
> + * @dev:	Device to check
> + * Return: parent's platform data, or NULL if none
>    */
>   void *dev_get_parent_plat(const struct udevice *dev);
>
> @@ -474,8 +496,8 @@ void *dev_get_parent_plat(const struct udevice *dev);
>    *
>    * This checks that dev is not NULL, but no other checks for now
>    *
> - * @dev		Device to check
> - * @return uclass's platform data, or NULL if none
> + * @dev:	Device to check
> + * Return: uclass's platform data, or NULL if none
>    */
>   void *dev_get_uclass_plat(const struct udevice *dev);
>
> @@ -484,8 +506,8 @@ void *dev_get_uclass_plat(const struct udevice *dev);
>    *
>    * This checks that dev is not NULL, but no other checks for now
>    *
> - * @dev		Device to check
> - * @return private data, or NULL if none
> + * @dev:	Device to check
> + * Return: private data, or NULL if none
>    */
>   void *dev_get_priv(const struct udevice *dev);
>
> @@ -498,8 +520,8 @@ void *dev_get_priv(const struct udevice *dev);
>    *
>    * This checks that dev is not NULL, but no other checks for now
>    *
> - * @dev		Device to check
> - * @return parent data, or NULL if none
> + * @dev:	Device to check
> + * Return: parent data, or NULL if none
>    */
>   void *dev_get_parent_priv(const struct udevice *dev);
>
> @@ -508,16 +530,16 @@ void *dev_get_parent_priv(const struct udevice *dev);
>    *
>    * This checks that dev is not NULL, but no other checks for now
>    *
> - * @dev		Device to check
> - * @return private uclass data for this device, or NULL if none
> + * @dev:	Device to check
> + * Return: private uclass data for this device, or NULL if none
>    */
>   void *dev_get_uclass_priv(const struct udevice *dev);
>
>   /**
> - * struct dev_get_parent() - Get the parent of a device
> + * dev_get_parent() - Get the parent of a device
>    *
>    * @child:	Child to check
> - * @return parent of child, or NULL if this is the root device
> + * Return: parent of child, or NULL if this is the root device
>    */
>   struct udevice *dev_get_parent(const struct udevice *child);
>
> @@ -529,13 +551,14 @@ struct udevice *dev_get_parent(const struct udevice *child);
>    * returns the associated data value for that compatible string. This is
>    * the 'data' field in struct udevice_id.
>    *
> - * As an example, consider this structure:
> - * static const struct udevice_id tegra_i2c_ids[] = {
> - *	{ .compatible = "nvidia,tegra114-i2c", .data = TYPE_114 },
> - *	{ .compatible = "nvidia,tegra20-i2c", .data = TYPE_STD },
> - *	{ .compatible = "nvidia,tegra20-i2c-dvc", .data = TYPE_DVC },
> - *	{ }
> - * };
> + * As an example, consider this structure: ::
> + *
> + *  static const struct udevice_id tegra_i2c_ids[] = {
> + *      { .compatible = "nvidia,tegra114-i2c", .data = TYPE_114 },
> + *      { .compatible = "nvidia,tegra20-i2c", .data = TYPE_STD },
> + *      { .compatible = "nvidia,tegra20-i2c-dvc", .data = TYPE_DVC },
> + *      { }
> + *  };
>    *
>    * When driver model finds a driver for this it will store the 'data' value
>    * corresponding to the compatible string it matches. This function returns
> @@ -544,7 +567,7 @@ struct udevice *dev_get_parent(const struct udevice *child);
>    * For USB devices, this is the driver_info field in struct usb_device_id.
>    *
>    * @dev:	Device to check
> - * @return driver data (0 if none is provided)
> + * Return: driver data (0 if none is provided)
>    */
>   ulong dev_get_driver_data(const struct udevice *dev);
>
> @@ -555,7 +578,7 @@ ulong dev_get_driver_data(const struct udevice *dev);
>    * driver's operations.
>    *
>    * @dev:	Device to check
> - * @return void pointer to driver's operations or NULL for NULL-dev or NULL-ops
> + * Return: void pointer to driver's operations or NULL for NULL-dev or NULL-ops
>    */
>   const void *dev_get_driver_ops(const struct udevice *dev);
>
> @@ -563,7 +586,7 @@ const void *dev_get_driver_ops(const struct udevice *dev);
>    * device_get_uclass_id() - return the uclass ID of a device
>    *
>    * @dev:	Device to check
> - * @return uclass ID for the device
> + * Return: uclass ID for the device
>    */
>   enum uclass_id device_get_uclass_id(const struct udevice *dev);
>
> @@ -573,7 +596,7 @@ enum uclass_id device_get_uclass_id(const struct udevice *dev);
>    * This checks that dev is not NULL.
>    *
>    * @dev:	Device to check
> - * @return  pointer to the uclass name for the device
> + * Return:  pointer to the uclass name for the device
>    */
>   const char *dev_get_uclass_name(const struct udevice *dev);
>
> @@ -583,11 +606,11 @@ const char *dev_get_uclass_name(const struct udevice *dev);
>    * Returns the numbered child, 0 being the first. This does not use
>    * sequence numbers, only the natural order.
>    *
> - * @dev:	Parent device to check
> + * @parent:	Parent device to check
>    * @index:	Child index
>    * @devp:	Returns pointer to device
> - * @return 0 if OK, -ENODEV if no such device, other error if the device fails
> - *	   to probe
> + * Return:
> + * 0 if OK, -ENODEV if no such device, other error if the device fails to probe
>    */
>   int device_get_child(const struct udevice *parent, int index,
>   		     struct udevice **devp);
> @@ -619,7 +642,7 @@ int device_get_decendent_count(const struct udevice *parent);
>    * @seq: Sequence number to find (0=first)
>    * @devp: Returns pointer to device (there is only one per for each seq).
>    * Set to NULL if none is found
> - * @return 0 if OK, -ENODEV if not found
> + * Return: 0 if OK, -ENODEV if not found
>    */
>   int device_find_child_by_seq(const struct udevice *parent, int seq,
>   			     struct udevice **devp);
> @@ -637,7 +660,7 @@ int device_find_child_by_seq(const struct udevice *parent, int seq,
>    * @seq: Sequence number to find (0=first)
>    * @devp: Returns pointer to device (there is only one per for each seq)
>    * Set to NULL if none is found
> - * @return 0 if OK, -ve on error
> + * Return: 0 if OK, -ve on error
>    */
>   int device_get_child_by_seq(const struct udevice *parent, int seq,
>   			    struct udevice **devp);
> @@ -650,7 +673,7 @@ int device_get_child_by_seq(const struct udevice *parent, int seq,
>    * @parent: Parent device
>    * @of_offset: Device tree offset to find
>    * @devp: Returns pointer to device if found, otherwise this is set to NULL
> - * @return 0 if OK, -ve on error
> + * Return: 0 if OK, -ve on error
>    */
>   int device_find_child_by_of_offset(const struct udevice *parent, int of_offset,
>   				   struct udevice **devp);
> @@ -665,7 +688,7 @@ int device_find_child_by_of_offset(const struct udevice *parent, int of_offset,
>    * @parent: Parent device
>    * @of_offset: Device tree offset to find
>    * @devp: Returns pointer to device if found, otherwise this is set to NULL
> - * @return 0 if OK, -ve on error
> + * Return: 0 if OK, -ve on error
>    */
>   int device_get_child_by_of_offset(const struct udevice *parent, int of_offset,
>   				  struct udevice **devp);
> @@ -680,7 +703,7 @@ int device_get_child_by_of_offset(const struct udevice *parent, int of_offset,
>    *
>    * @node: Device tree ofnode to find
>    * @devp: Returns pointer to device if found, otherwise this is set to NULL
> - * @return 0 if OK, -ve on error
> + * Return: 0 if OK, -ve on error
>    */
>
>   int device_find_global_by_ofnode(ofnode node, struct udevice **devp);
> @@ -695,7 +718,7 @@ int device_find_global_by_ofnode(ofnode node, struct udevice **devp);
>    *
>    * @node: Device tree ofnode to find
>    * @devp: Returns pointer to device if found, otherwise this is set to NULL
> - * @return 0 if OK, -ve on error
> + * Return: 0 if OK, -ve on error
>    */
>   int device_get_global_by_ofnode(ofnode node, struct udevice **devp);
>
> @@ -715,7 +738,7 @@ int device_get_global_by_ofnode(ofnode node, struct udevice **devp);
>    *
>    * @idx: Index number of the driver_info/udevice structure (0=first)
>    * @devp: Returns pointer to device if found, otherwise this is set to NULL
> - * @return 0 if OK, -ve on error
> + * Return: 0 if OK, -ve on error
>    */
>   int device_get_by_ofplat_idx(uint idx, struct udevice **devp);
>
> @@ -724,7 +747,7 @@ int device_get_by_ofplat_idx(uint idx, struct udevice **devp);
>    *
>    * @parent: Parent device to search
>    * @devp: Returns first child device, or NULL if none
> - * @return 0
> + * Return: 0
>    */
>   int device_find_first_child(const struct udevice *parent,
>   			    struct udevice **devp);
> @@ -734,7 +757,7 @@ int device_find_first_child(const struct udevice *parent,
>    *
>    * @devp: Pointer to previous child device on entry. Returns pointer to next
>    *		child device, or NULL if none
> - * @return 0
> + * Return: 0
>    */
>   int device_find_next_child(struct udevice **devp);
>
> @@ -749,7 +772,7 @@ int device_find_next_child(struct udevice **devp);
>    * @parent:	Parent device to search
>    * @uclass_id:	Uclass to look for
>    * @devp:	Returns device found, if any, else NULL
> - * @return 0 if found, else -ENODEV
> + * Return: 0 if found, else -ENODEV
>    */
>   int device_find_first_inactive_child(const struct udevice *parent,
>   				     enum uclass_id uclass_id,
> @@ -761,7 +784,7 @@ int device_find_first_inactive_child(const struct udevice *parent,
>    * @parent: Parent device to search
>    * @uclass_id:	Uclass to look for
>    * @devp: Returns first child device in that uclass, if any, else NULL
> - * @return 0 if found, else -ENODEV
> + * Return: 0 if found, else -ENODEV
>    */
>   int device_find_first_child_by_uclass(const struct udevice *parent,
>   				      enum uclass_id uclass_id,
> @@ -774,7 +797,7 @@ int device_find_first_child_by_uclass(const struct udevice *parent,
>    * @name:	Name to look for
>    * @len:	Length of the name
>    * @devp:	Returns device found, if any
> - * @return 0 if found, else -ENODEV
> + * Return: 0 if found, else -ENODEV
>    */
>   int device_find_child_by_namelen(const struct udevice *parent, const char *name,
>   				 int len, struct udevice **devp);
> @@ -785,7 +808,7 @@ int device_find_child_by_namelen(const struct udevice *parent, const char *name,
>    * @parent:	Parent device to search
>    * @name:	Name to look for
>    * @devp:	Returns device found, if any
> - * @return 0 if found, else -ENODEV
> + * Return: 0 if found, else -ENODEV
>    */
>   int device_find_child_by_name(const struct udevice *parent, const char *name,
>   			      struct udevice **devp);
> @@ -798,7 +821,7 @@ int device_find_child_by_name(const struct udevice *parent, const char *name,
>    *
>    * @parent: Parent to check
>    * @devp: Returns child that was found, if any
> - * @return 0 on success, -ENODEV if no children, other -ve on error
> + * Return: 0 on success, -ENODEV if no children, other -ve on error
>    */
>   int device_first_child_ofdata_err(struct udevice *parent,
>   				  struct udevice **devp);
> @@ -811,7 +834,7 @@ int device_first_child_ofdata_err(struct udevice *parent,
>    *
>    * @devp: On entry, points to the previous child; on exit returns the child that
>    *	was found, if any
> - * @return 0 on success, -ENODEV if no children, other -ve on error
> + * Return: 0 on success, -ENODEV if no children, other -ve on error
>    */
>   int device_next_child_ofdata_err(struct udevice **devp);
>
> @@ -822,7 +845,7 @@ int device_next_child_ofdata_err(struct udevice **devp);
>    *
>    * @parent:	Parent device to search
>    * @devp:	Returns device found, if any
> - * @return 0 if found, -ENODEV if not, -ve error if device failed to probe
> + * Return: 0 if found, -ENODEV if not, -ve error if device failed to probe
>    */
>   int device_first_child_err(struct udevice *parent, struct udevice **devp);
>
> @@ -833,7 +856,7 @@ int device_first_child_err(struct udevice *parent, struct udevice **devp);
>    *
>    * @devp: On entry, pointer to device to lookup. On exit, returns pointer
>    * to the next sibling if no error occurred
> - * @return 0 if found, -ENODEV if not, -ve error if device failed to probe
> + * Return: 0 if found, -ENODEV if not, -ve error if device failed to probe
>    */
>   int device_next_child_err(struct udevice **devp);
>
> @@ -841,7 +864,7 @@ int device_next_child_err(struct udevice **devp);
>    * device_has_children() - check if a device has any children
>    *
>    * @dev:	Device to check
> - * @return true if the device has one or more children
> + * Return: true if the device has one or more children
>    */
>   bool device_has_children(const struct udevice *dev);
>
> @@ -849,7 +872,7 @@ bool device_has_children(const struct udevice *dev);
>    * device_has_active_children() - check if a device has any active children
>    *
>    * @dev:	Device to check
> - * @return true if the device has one or more children and at least one of
> + * Return: true if the device has one or more children and at least one of
>    * them is active (probed).
>    */
>   bool device_has_active_children(const struct udevice *dev);
> @@ -862,7 +885,7 @@ bool device_has_active_children(const struct udevice *dev);
>    * view of devices is being displayed.
>    *
>    * @dev:	Device to check
> - * @return true if there are no more siblings after this one - i.e. is it
> + * Return: true if there are no more siblings after this one - i.e. is it
>    * last in the list.
>    */
>   bool device_is_last_sibling(const struct udevice *dev);
> @@ -880,7 +903,7 @@ bool device_is_last_sibling(const struct udevice *dev);
>    * @dev:	Device to update
>    * @name:	New name (this string is allocated new memory and attached to
>    *		the device)
> - * @return 0 if OK, -ENOMEM if there is not enough memory to allocate the
> + * Return: 0 if OK, -ENOMEM if there is not enough memory to allocate the
>    * string
>    */
>   int device_set_name(struct udevice *dev, const char *name);
> @@ -903,7 +926,7 @@ void device_set_name_alloced(struct udevice *dev);
>    * @dev:	udevice pointer for which compatible needs to be verified.
>    * @compat:	Compatible string which needs to verified in the given
>    *		device
> - * @return true if OK, false if the compatible is not found
> + * Return: true if OK, false if the compatible is not found
>    */
>   bool device_is_compatible(const struct udevice *dev, const char *compat);
>
> @@ -914,7 +937,7 @@ bool device_is_compatible(const struct udevice *dev, const char *compat);
>    * This allows to check whether the machine is comaptible with the compat.
>    *
>    * @compat:	Compatible string which needs to verified
> - * @return true if OK, false if the compatible is not found
> + * Return: true if OK, false if the compatible is not found
>    */
>   bool of_machine_is_compatible(const char *compat);
>
> @@ -922,7 +945,7 @@ bool of_machine_is_compatible(const char *compat);
>    * dev_disable_by_path() - Disable a device given its device tree path
>    *
>    * @path:	The device tree path identifying the device to be disabled
> - * @return 0 on success, -ve on error
> + * Return: 0 on success, -ve on error
>    */
>   int dev_disable_by_path(const char *path);
>
> @@ -930,7 +953,7 @@ int dev_disable_by_path(const char *path);
>    * dev_enable_by_path() - Enable a device given its device tree path
>    *
>    * @path:	The device tree path identifying the device to be enabled
> - * @return 0 on success, -ve on error
> + * Return: 0 on success, -ve on error
>    */
>   int dev_enable_by_path(const char *path);
>
> @@ -938,7 +961,7 @@ int dev_enable_by_path(const char *path);
>    * device_is_on_pci_bus - Test if a device is on a PCI bus
>    *
>    * @dev:	device to test
> - * @return:	true if it is on a PCI bus, false otherwise
> + * Return:	true if it is on a PCI bus, false otherwise
>    */
>   static inline bool device_is_on_pci_bus(const struct udevice *dev)
>   {
> @@ -971,7 +994,7 @@ static inline bool device_is_on_pci_bus(const struct udevice *dev)
>    *
>    * This stops when it gets an error, with @pos set to the device that failed to
>    * read ofdata.
> -
> + *
>    * This creates a for() loop which works through the available children of
>    * a device in order from start to end. Device ofdata is read by calling
>    * device_of_to_plat() on each one. The devices are not probed.
> @@ -1012,7 +1035,7 @@ static inline bool device_is_on_pci_bus(const struct udevice *dev)
>    * be bound.
>    *
>    * @dev:	Device to scan
> - * @return 0 if OK, -ve on error
> + * Return: 0 if OK, -ve on error
>    */
>   int dm_scan_fdt_dev(struct udevice *dev);
>

Re: [PATCH 6/9] doc: add include/dm/devres.h to the HTML documentation

[Heinrich Schuchardt]

On 1/12/22 10:53, Patrick Delaunay wrote:
> Correct Sphinx style comments in include/dm/devres.h
> and add the driver model device resource API, devres_*(),
> to the HTML documentation.
>
> Signed-off-by: Patrick Delaunay<patrick.delaunay@foss.st.com>
> ---

Reviewed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>

Re: [PATCH 7/9] doc: add include/dm/read.h to the HTML documentation

[Heinrich Schuchardt]

On 1/12/22 10:53, Patrick Delaunay wrote:
> Correct Sphinx style comments in include/dm/read.h
> and add the device read from device tree API to the HTML
> documentation.
>
> Signed-off-by: Patrick Delaunay<patrick.delaunay@foss.st.com>

Reviewed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>

Re: [PATCH 8/9] doc: add include/dm/of*.h to the HTML documentation

[Heinrich Schuchardt]

On 1/12/22 10:53, Patrick Delaunay wrote:
> Correct Sphinx style comments in include/dm/ofnode.h
> and add the device tree node API to the HTML documentation;
> the ofnode functions are compatible with Live tree or with flat
> device tree.
>
> Signed-off-by: Patrick Delaunay<patrick.delaunay@foss.st.com>
> ---

Reviewed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>

Re: [PATCH 1/9] doc: add include/dm/uclass.h to the HTML documentation

[Patrick DELAUNAY]

Hi Heinrich,

On 1/15/22 9:24 AM, Heinrich Schuchardt wrote:
> On 1/12/22 10:53, Patrick Delaunay wrote:
>> Correct Sphinx style comments in include/dm/uclass.h
>> and add the driver model UCLASS API to the HTML documentation.
>>
>> Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
>> ---
>>
>>   doc/api/dm.rst      |  9 ++++++
>>   doc/api/index.rst   |  1 +
>>   include/dm/uclass.h | 75 ++++++++++++++++++++++-----------------------
>>   3 files changed, 47 insertions(+), 38 deletions(-)
>>   create mode 100644 doc/api/dm.rst
>>
>> diff --git a/doc/api/dm.rst b/doc/api/dm.rst
>> new file mode 100644
>> index 0000000000..edce25da51
>> --- /dev/null
>> +++ b/doc/api/dm.rst
>> @@ -0,0 +1,9 @@
>> +.. SPDX-License-Identifier: GPL-2.0+
>> +
>> +Driver Model
>> +============
>> +
>> +Uclass and Driver
>> +-----------------
>> +
>> +.. kernel-doc:: include/dm/uclass.h
>> diff --git a/doc/api/index.rst b/doc/api/index.rst
>> index 806c7385a6..3f36174167 100644
>> --- a/doc/api/index.rst
>> +++ b/doc/api/index.rst
>> @@ -7,6 +7,7 @@ U-Boot API documentation
>>      :maxdepth: 2
>>
>>      dfu
>> +   dm
>>      efi
>>      getopt
>>      linker_lists
>> diff --git a/include/dm/uclass.h b/include/dm/uclass.h
>> index f1fd2ba246..a12a872d94 100644
>> --- a/include/dm/uclass.h
>> +++ b/include/dm/uclass.h
>> @@ -84,7 +84,7 @@ struct udevice;
>>    * its children. If non-zero this is the size of this data, to be 
>> allocated
>>    * in the child device's parent_plat pointer. This value is only 
>> used as
>>    * a fallback if this member is 0 in the driver.
>> - * @flags: Flags for this uclass (DM_UC_...)
>> + * @flags: Flags for this uclass ``(DM_UC_...)``
>>    */
>>   struct uclass_driver {
>>       const char *name;
>> @@ -127,17 +127,16 @@ struct uclass_driver {
>>    * build time. Before this is used, an extern UCLASS_DRIVER() must 
>> have been
>>    * declared.
>>    *
>> - * For example:
>> + * For example: ::
>
> Nits:
> "For example::" has the same effect. I will change this when merging.
>
ok.

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#literal-blocks

I miss the 'Fully minimized form:' or when I test the html output

I let a space before the Literal Blocks => "Paragraph ::"

FYI: I do the same issue in several location I think.


> Reviewed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
>
>>

Patrick