of: Fix kerneldoc output formatting

[ Upstream commit 62f026f082e4d762a47b43ea693b38f025122332 ]

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

Cc: Frank Rowand <frowand.list@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Rob Herring <robh@kernel.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/20210326192606.3702739-1-robh@kernel.org
Stable-dep-of: d79972789d17 ("of: dynamic: Fix of_reconfig_get_state_change() return value documentation")
Signed-off-by: Sasha Levin <sashal@kernel.org>

drivers/of/base.c

@@ -654,7 +654,7 @@ EXPORT_SYMBOL(of_device_is_big_endian);
  * of_get_parent - Get a node's parent if any
  * @node:	Node to get parent
  *
- *	Returns a node pointer with refcount incremented, use
+ * Return: A node pointer with refcount incremented, use
  * of_node_put() on it when done.
  */
 struct device_node *of_get_parent(const struct device_node *node)
@@ -680,7 +680,7 @@ EXPORT_SYMBOL(of_get_parent);
  * refcount on the passed node, making it suitable for iterating
  * through a node's parents.
  *
- *	Returns a node pointer with refcount incremented, use
+ * Return: A node pointer with refcount incremented, use
  * of_node_put() on it when done.
  */
 struct device_node *of_get_next_parent(struct device_node *node)
@@ -723,7 +723,7 @@ static struct device_node *__of_get_next_child(const struct device_node *node,
  * @node:	parent node
  * @prev:	previous child of the parent node, or NULL to get first
  *
- *	Returns a node pointer with refcount incremented, use of_node_put() on
+ * Return: A node pointer with refcount incremented, use of_node_put() on
  * it when done. Returns NULL when prev is the last child. Decrements the
  * refcount of prev.
  */
@@ -775,7 +775,7 @@ EXPORT_SYMBOL(of_get_next_available_child);
  * of_get_next_cpu_node - Iterate on cpu nodes
  * @prev:	previous child of the /cpus node, or NULL to get first
  *
- *	Returns a cpu node pointer with refcount incremented, use of_node_put()
+ * Return: A cpu node pointer with refcount incremented, use of_node_put()
  * on it when done. Returns NULL when prev is the last child. Decrements
  * the refcount of prev.
  */
@@ -840,7 +840,7 @@ EXPORT_SYMBOL(of_get_compatible_child);
  *
  * This function looks for child node for given matching name
  *
- *	Returns a node pointer if found, with refcount incremented, use
+ * Return: A node pointer if found, with refcount incremented, use
  * of_node_put() on it when done.
  * Returns NULL if node is not found.
  */
@@ -903,11 +903,11 @@ struct device_node *__of_find_node_by_full_path(struct device_node *node,
  *       a ':' separator.
  *
  * Valid paths:
- *		/foo/bar	Full path
+ *  * /foo/bar	Full path
- *		foo		Valid alias
+ *  * foo	Valid alias
- *		foo/bar		Valid alias + relative path
+ *  * foo/bar	Valid alias + relative path
  *
- *	Returns a node pointer with refcount incremented, use
+ * Return: A node pointer with refcount incremented, use
  * of_node_put() on it when done.
  */
 struct device_node *of_find_node_opts_by_path(const char *path, const char **opts)
@@ -965,7 +965,7 @@ EXPORT_SYMBOL(of_find_node_opts_by_path);
  *		returned. of_node_put() will be called on @from.
  * @name:	The name string to match against
  *
- *	Returns a node pointer with refcount incremented, use
+ * Return: A node pointer with refcount incremented, use
  * of_node_put() on it when done.
  */
 struct device_node *of_find_node_by_name(struct device_node *from,
@@ -993,7 +993,7 @@ EXPORT_SYMBOL(of_find_node_by_name);
  *		called on from for you.
  * @type:	The type string to match against
  *
- *	Returns a node pointer with refcount incremented, use
+ * Return: A node pointer with refcount incremented, use
  * of_node_put() on it when done.
  */
 struct device_node *of_find_node_by_type(struct device_node *from,
@@ -1023,7 +1023,7 @@ EXPORT_SYMBOL(of_find_node_by_type);
  * @compatible:	The string to match to one of the tokens in the device
  *		"compatible" list.
  *
- *	Returns a node pointer with refcount incremented, use
+ * Return: A node pointer with refcount incremented, use
  * of_node_put() on it when done.
  */
 struct device_node *of_find_compatible_node(struct device_node *from,
@@ -1052,7 +1052,7 @@ EXPORT_SYMBOL(of_find_compatible_node);
  *		returned. of_node_put() will be called on it
  * @prop_name:	The name of the property to look for.
  *
- *	Returns a node pointer with refcount incremented, use
+ * Return: A node pointer with refcount incremented, use
  * of_node_put() on it when done.
  */
 struct device_node *of_find_node_with_property(struct device_node *from,
@@ -1130,7 +1130,7 @@ EXPORT_SYMBOL(of_match_node);
  * @matches:	array of of device match structures to search in
  * @match:	Updated to point at the matches entry which matched
  *
- *	Returns a node pointer with refcount incremented, use
+ * Return: A node pointer with refcount incremented, use
  * of_node_put() on it when done.
  */
 struct device_node *of_find_matching_node_and_match(struct device_node *from,
@@ -1465,21 +1465,21 @@ EXPORT_SYMBOL(of_parse_phandle);
  * 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>;
- * }
+ *  };
  *
- * To get a device_node of the `node2' node you may call this:
+ * To get a device_node of the ``node2`` node you may call this:
  * of_parse_phandle_with_args(node3, "list", "#list-cells", 1, &args);
  */
 int of_parse_phandle_with_args(const struct device_node *np, const char *list_name,
@@ -1517,15 +1517,15 @@ EXPORT_SYMBOL(of_parse_phandle_with_args);
  * 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>;
- * }
+ *  };
  *
  *  phandle3: node3 {
  *  	#list-cells = <1>;
@@ -1537,9 +1537,9 @@ EXPORT_SYMBOL(of_parse_phandle_with_args);
  *
  *  node4 {
  *  	list = <&phandle1 1 2 &phandle3 0>;
- * }
+ *  };
  *
- * To get a device_node of the `node2' node you may call this:
+ * To get a device_node of the ``node2`` node you may call this:
  * of_parse_phandle_with_args(node4, "list", "list", 1, &args);
  */
 int of_parse_phandle_with_args_map(const struct device_node *np,
@@ -1699,19 +1699,19 @@ EXPORT_SYMBOL(of_parse_phandle_with_args_map);
  * Caller is responsible to call of_node_put() on the returned out_args->np
  * pointer.
  *
- * Example:
+ * Example::
  *
  *  phandle1: node1 {
- * }
+ *  };
  *
  *  phandle2: node2 {
- * }
+ *  };
  *
  *  node3 {
  *  	list = <&phandle1 0 2 &phandle2 2 3>;
- * }
+ *  };
  *
- * To get a device_node of the `node2' node you may call this:
+ * To get a device_node of the ``node2`` node you may call this:
  * of_parse_phandle_with_fixed_args(node3, "list", 2, 1, &args);
  */
 int of_parse_phandle_with_fixed_args(const struct device_node *np,
@@ -1957,13 +1957,12 @@ static void of_alias_add(struct alias_prop *ap, struct device_node *np,
 
 /**
  * of_alias_scan - Scan all properties of the 'aliases' node
+ * @dt_alloc:	An allocator that provides a virtual address to memory
+ *		for storing the resulting tree
  *
  * The function scans all the properties of the 'aliases' node and populates
  * the global lookup table with the properties.  It returns the
  * number of alias properties found, or an error code in case of failure.
- *
- * @dt_alloc:	An allocator that provides a virtual address to memory
- *		for storing the resulting tree
  */
 void of_alias_scan(void * (*dt_alloc)(u64 size, u64 align))
 {
@@ -2161,7 +2160,7 @@ EXPORT_SYMBOL_GPL(of_console_check);
  * of_find_next_cache_node - Find a node's subsidiary cache
  * @np:	node of type "cpu" or "cache"
  *
- *	Returns a node pointer with refcount incremented, use
+ * Return: A node pointer with refcount incremented, use
  * of_node_put() on it when done.  Caller should hold a reference
  * to np.
  */

drivers/of/fdt.c

@@ -349,11 +349,6 @@ static int unflatten_dt_nodes(const void *blob,
 
 /**
  * __unflatten_device_tree - create tree of device_nodes from flat blob
- *
- * unflattens a device-tree, creating the
- * tree of struct device_node. It also fills the "name" and "type"
- * pointers of the nodes so the normal device-tree walking functions
- * can be used.
  * @blob: The blob to expand
  * @dad: Parent device node
  * @mynodes: The device_node tree created by the call
@@ -361,6 +356,10 @@ static int unflatten_dt_nodes(const void *blob,
  * for the resulting tree
  * @detached: if true set OF_DETACHED on @mynodes
  *
+ * unflattens a device-tree, creating the tree of struct device_node. It also
+ * fills the "name" and "type" pointers of the nodes so the normal device-tree
+ * walking functions can be used.
+ *
  * Returns NULL on failure or the memory chunk containing the unflattened
  * device tree on success.
  */