[PATCH v2 00/10] Rid W=1 warnings from OF

[PATCH v2 00/10] Rid W=1 warnings from OF

[Lee Jones]

This set is part of a larger effort attempting to clean-up W=1
kernel builds, which are currently overwhelmingly riddled with
niggly little warnings.

v2:
 - Provided some descriptions to exported functions

Lee Jones (10):
  of: device: Fix function name in header and provide missing
    descriptions
  of: dynamic: Fix incorrect parameter name and provide missing
    descriptions
  of: platform: Demote kernel-doc abuse
  of: base: Fix some formatting issues and provide missing descriptions
  of: property: Provide missing member description and remove excess
    param
  of: address: Provide descriptions for 'of_address_to_resource's params
  of: fdt: Demote kernel-doc abuses and fix function naming
  of: of_net: Provide function name and param description
  of: overlay: Fix function name disparity
  of: of_reserved_mem: Demote kernel-doc abuses

 drivers/of/address.c         |  3 +++
 drivers/of/base.c            | 16 +++++++++++-----
 drivers/of/device.c          |  7 ++++++-
 drivers/of/dynamic.c         |  4 +++-
 drivers/of/fdt.c             | 23 ++++++++++++-----------
 drivers/of/of_net.c          |  3 +++
 drivers/of/of_reserved_mem.c |  6 +++---
 drivers/of/overlay.c         |  2 +-
 drivers/of/platform.c        |  2 +-
 drivers/of/property.c        |  2 +-
 10 files changed, 44 insertions(+), 24 deletions(-)

Cc: Andrew Lunn <andrew@lunn.ch>
Cc: Anton Vorontsov <anton@enomsg.org>
Cc: benh@kernel.crashing.org
Cc: Colin Cross <ccross@android.com>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: devicetree@vger.kernel.org
Cc: Frank Rowand <frowand.list@gmail.com>
Cc: Heiner Kallweit <hkallweit1@gmail.com>
Cc: Josh Cartwright <joshc@codeaurora.org>
Cc: Kees Cook <keescook@chromium.org>
Cc: Marek Szyprowski <m.szyprowski@samsung.com>
Cc: netdev@vger.kernel.org
Cc: Pantelis Antoniou <pantelis.antoniou@konsulko.com>
Cc: Rob Herring <robh+dt@kernel.org>
Cc: Russell King <linux@armlinux.org.uk>
Cc: Tony Luck <tony.luck@intel.com>
-- 
2.27.0

[PATCH 01/10] of: device: Fix function name in header and provide missing descriptions

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/of/device.c:72: warning: expecting prototype for of_dma_configure(). Prototype was for of_dma_configure_id() instead
 drivers/of/device.c:263: warning: Function parameter or member 'dev' not described in 'of_device_modalias'
 drivers/of/device.c:263: warning: Function parameter or member 'str' not described in 'of_device_modalias'
 drivers/of/device.c:263: warning: Function parameter or member 'len' not described in 'of_device_modalias'
 drivers/of/device.c:280: warning: Function parameter or member 'dev' not described in 'of_device_uevent'
 drivers/of/device.c:280: warning: Function parameter or member 'env' not described in 'of_device_uevent'

Cc: Rob Herring <robh+dt@kernel.org>
Cc: Frank Rowand <frowand.list@gmail.com>
Cc: devicetree@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/of/device.c | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/drivers/of/device.c b/drivers/of/device.c
index 6cb86de404f1c..c5a9473a5fb1a 100644
--- a/drivers/of/device.c
+++ b/drivers/of/device.c
@@ -53,7 +53,7 @@ int of_device_add(struct platform_device *ofdev)
 }
 
 /**
- * of_dma_configure - Setup DMA configuration
+ * of_dma_configure_id - Setup DMA configuration
  * @dev:	Device to apply DMA configuration
  * @np:		Pointer to OF node having DMA configuration
  * @force_dma:  Whether device is to be set up by of_dma_configure() even if
@@ -258,6 +258,9 @@ EXPORT_SYMBOL_GPL(of_device_request_module);
 
 /**
  * of_device_modalias - Fill buffer with newline terminated modalias string
+ * @dev:	Calling device
+ * @str:	Modalias string
+ * @len:	Size of @str
  */
 ssize_t of_device_modalias(struct device *dev, char *str, ssize_t len)
 {
@@ -275,6 +278,8 @@ EXPORT_SYMBOL_GPL(of_device_modalias);
 
 /**
  * of_device_uevent - Display OF related uevent information
+ * @dev:	Device to apply DMA configuration
+ * @env:	Kernel object's userspace event reference
  */
 void of_device_uevent(struct device *dev, struct kobj_uevent_env *env)
 {
-- 
2.27.0

[PATCH 02/10] of: dynamic: Fix incorrect parameter name and provide missing descriptions

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/of/dynamic.c:234: warning: Function parameter or member 'np' not described in 'of_attach_node'
 drivers/of/dynamic.c:286: warning: Function parameter or member 'np' not described in 'of_detach_node'
 drivers/of/dynamic.c:326: warning: Function parameter or member 'kobj' not described in 'of_node_release'
 drivers/of/dynamic.c:326: warning: Excess function parameter 'kref' description in 'of_node_release'

Cc: Rob Herring <robh+dt@kernel.org>
Cc: Frank Rowand <frowand.list@gmail.com>
Cc: devicetree@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/of/dynamic.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/drivers/of/dynamic.c b/drivers/of/dynamic.c
index 9a824decf61f1..1d7a22e44d787 100644
--- a/drivers/of/dynamic.c
+++ b/drivers/of/dynamic.c
@@ -229,6 +229,7 @@ static void __of_attach_node(struct device_node *np)
 
 /**
  * of_attach_node() - Plug a device node into the tree and global list.
+ * @np:		Pointer to the caller's Device Node
  */
 int of_attach_node(struct device_node *np)
 {
@@ -281,6 +282,7 @@ void __of_detach_node(struct device_node *np)
 
 /**
  * of_detach_node() - "Unplug" a node from the device tree.
+ * @np:		Pointer to the caller's Device Node
  */
 int of_detach_node(struct device_node *np)
 {
@@ -318,7 +320,7 @@ static void property_list_free(struct property *prop_list)
 
 /**
  * of_node_release() - release a dynamically allocated node
- * @kref: kref element of the node to be released
+ * @kobj: kernel object of the node to be released
  *
  * In of_node_put() this function is passed to kref_put() as the destructor.
  */
-- 
2.27.0

[PATCH 03/10] of: platform: Demote kernel-doc abuse

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/of/platform.c:298: warning: Function parameter or member 'lookup' not described in 'of_dev_lookup'
 drivers/of/platform.c:298: warning: Function parameter or member 'np' not described in 'of_dev_lookup'

Cc: Rob Herring <robh+dt@kernel.org>
Cc: Frank Rowand <frowand.list@gmail.com>
Cc: Kees Cook <keescook@chromium.org>
Cc: Anton Vorontsov <anton@enomsg.org>
Cc: Colin Cross <ccross@android.com>
Cc: Tony Luck <tony.luck@intel.com>
Cc: benh@kernel.crashing.org
Cc: devicetree@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/of/platform.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/of/platform.c b/drivers/of/platform.c
index 0da86209ddaab..0ed46d301431b 100644
--- a/drivers/of/platform.c
+++ b/drivers/of/platform.c
@@ -290,7 +290,7 @@ static struct amba_device *of_amba_device_create(struct device_node *node,
 }
 #endif /* CONFIG_ARM_AMBA */
 
-/**
+/*
  * of_dev_lookup() - Given a device node, lookup the preferred Linux name
  */
 static const struct of_dev_auxdata *of_dev_lookup(const struct of_dev_auxdata *lookup,
-- 
2.27.0

[PATCH 04/10] of: base: Fix some formatting issues and provide missing descriptions

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/of/base.c:315: warning: Function parameter or member 'cpun' not described in '__of_find_n_match_cpu_property'
 drivers/of/base.c:315: warning: Function parameter or member 'prop_name' not described in '__of_find_n_match_cpu_property'
 drivers/of/base.c:315: warning: Function parameter or member 'cpu' not described in '__of_find_n_match_cpu_property'
 drivers/of/base.c:315: warning: Function parameter or member 'thread' not described in '__of_find_n_match_cpu_property'
 drivers/of/base.c:315: warning: expecting prototype for property holds the physical id of the(). Prototype was for __of_find_n_match_cpu_property() instead
 drivers/of/base.c:1139: warning: Function parameter or member 'match' not described in 'of_find_matching_node_and_match'
 drivers/of/base.c:1779: warning: Function parameter or member 'np' not described in '__of_add_property'
 drivers/of/base.c:1779: warning: Function parameter or member 'prop' not described in '__of_add_property'
 drivers/of/base.c:1800: warning: Function parameter or member 'np' not described in 'of_add_property'
 drivers/of/base.c:1800: warning: Function parameter or member 'prop' not described in 'of_add_property'
 drivers/of/base.c:1849: warning: Function parameter or member 'np' not described in 'of_remove_property'
 drivers/of/base.c:1849: warning: Function parameter or member 'prop' not described in 'of_remove_property'
 drivers/of/base.c:2137: warning: Function parameter or member 'dn' not described in 'of_console_check'
 drivers/of/base.c:2137: warning: Function parameter or member 'name' not described in 'of_console_check'
 drivers/of/base.c:2137: warning: Function parameter or member 'index' not described in 'of_console_check'

Cc: Rob Herring <robh+dt@kernel.org>
Cc: Frank Rowand <frowand.list@gmail.com>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: devicetree@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/of/base.c | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/drivers/of/base.c b/drivers/of/base.c
index 8a348f0d3c5e7..457d1ec27300b 100644
--- a/drivers/of/base.c
+++ b/drivers/of/base.c
@@ -305,7 +305,7 @@ bool __weak arch_match_cpu_phys_id(int cpu, u64 phys_id)
 	return (u32)phys_id == cpu;
 }
 
-/**
+/*
  * Checks if the given "prop_name" property holds the physical id of the
  * core/thread corresponding to the logical cpu 'cpu'. If 'thread' is not
  * NULL, local thread number within the core is returned in it.
@@ -1128,7 +1128,7 @@ EXPORT_SYMBOL(of_match_node);
  *			will; typically, you pass what the previous call
  *			returned. of_node_put() will be called on it
  *	@matches:	array of of device match structures to search in
- *	@match		Updated to point at the matches entry which matched
+ *	@match:		Updated to point at the matches entry which matched
  *
  *	Returns a node pointer with refcount incremented, use
  *	of_node_put() on it when done.
@@ -1774,6 +1774,8 @@ EXPORT_SYMBOL(of_count_phandle_with_args);
 
 /**
  * __of_add_property - Add a property to a node without lock operations
+ * @np:		Caller's Device Node
+ * @prob:	Property to add
  */
 int __of_add_property(struct device_node *np, struct property *prop)
 {
@@ -1795,6 +1797,8 @@ int __of_add_property(struct device_node *np, struct property *prop)
 
 /**
  * of_add_property - Add a property to a node
+ * @np:		Caller's Device Node
+ * @prob:	Property to add
  */
 int of_add_property(struct device_node *np, struct property *prop)
 {
@@ -1839,6 +1843,8 @@ int __of_remove_property(struct device_node *np, struct property *prop)
 
 /**
  * of_remove_property - Remove a property from a node.
+ * @np:		Caller's Device Node
+ * @prob:	Property to remove
  *
  * Note that we don't actually remove it, since we have given out
  * who-knows-how-many pointers to the data using get-property.
@@ -2125,9 +2131,9 @@ EXPORT_SYMBOL_GPL(of_alias_get_highest_id);
 
 /**
  * of_console_check() - Test and setup console for DT setup
- * @dn - Pointer to device node
- * @name - Name to use for preferred console without index. ex. "ttyS"
- * @index - Index to use for preferred console.
+ * @dn: Pointer to device node
+ * @name: Name to use for preferred console without index. ex. "ttyS"
+ * @index: Index to use for preferred console.
  *
  * Check if the given device node matches the stdout-path property in the
  * /chosen node. If it does then register it as the preferred console and return
-- 
2.27.0

[PATCH 05/10] of: property: Provide missing member description and remove excess param

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/of/property.c:1239: warning: Function parameter or member 'optional' not described in 'supplier_bindings'
 drivers/of/property.c:1366: warning: Excess function parameter 'dev' description in 'of_link_property'

Cc: Rob Herring <robh+dt@kernel.org>
Cc: Frank Rowand <frowand.list@gmail.com>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: devicetree@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/of/property.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/of/property.c b/drivers/of/property.c
index 23816959c6966..c000ed01db018 100644
--- a/drivers/of/property.c
+++ b/drivers/of/property.c
@@ -1225,6 +1225,7 @@ static struct device_node *parse_##fname(struct device_node *np,	     \
  * @parse_prop.prop_name: Name of property holding a phandle value
  * @parse_prop.index: For properties holding a list of phandles, this is the
  *		      index into the list
+ * @optional: Describes whether a supplier is mandatory or not
  *
  * Returns:
  * parse_prop() return values are
@@ -1344,7 +1345,6 @@ static const struct supplier_bindings of_supplier_bindings[] = {
 
 /**
  * of_link_property - Create device links to suppliers listed in a property
- * @dev: Consumer device
  * @con_np: The consumer device tree node which contains the property
  * @prop_name: Name of property to be parsed
  *
-- 
2.27.0

[PATCH 06/10] of: address: Provide descriptions for 'of_address_to_resource's params

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/of/address.c:868: warning: Function parameter or member 'dev' not described in 'of_address_to_resource'
 drivers/of/address.c:868: warning: Function parameter or member 'index' not described in 'of_address_to_resource'
 drivers/of/address.c:868: warning: Function parameter or member 'r' not described in 'of_address_to_resource'

Cc: Rob Herring <robh+dt@kernel.org>
Cc: Frank Rowand <frowand.list@gmail.com>
Cc: devicetree@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/of/address.c | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/drivers/of/address.c b/drivers/of/address.c
index 73ddf2540f3fe..7de41abe7153f 100644
--- a/drivers/of/address.c
+++ b/drivers/of/address.c
@@ -857,6 +857,9 @@ static int __of_address_to_resource(struct device_node *dev,
 
 /**
  * of_address_to_resource - Translate device tree address and return as resource
+ * @dev:	Caller's Device Node
+ * @index:	Index into the array
+ * @r:		Pointer to resource array
  *
  * Note that if your address is a PIO address, the conversion will fail if
  * the physical address can't be internally converted to an IO token with
-- 
2.27.0

[PATCH 07/10] of: fdt: Demote kernel-doc abuses and fix function naming

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/of/fdt.c:478: warning: Function parameter or member 'node' not described in '__reserved_mem_reserve_reg'
 drivers/of/fdt.c:478: warning: Function parameter or member 'uname' not described in '__reserved_mem_reserve_reg'
 drivers/of/fdt.c:525: warning: Function parameter or member 'node' not described in '__reserved_mem_check_root'
 drivers/of/fdt.c:547: warning: Function parameter or member 'node' not described in '__fdt_scan_reserved_mem'
 drivers/of/fdt.c:547: warning: Function parameter or member 'uname' not described in '__fdt_scan_reserved_mem'
 drivers/of/fdt.c:547: warning: Function parameter or member 'depth' not described in '__fdt_scan_reserved_mem'
 drivers/of/fdt.c:547: warning: Function parameter or member 'data' not described in '__fdt_scan_reserved_mem'
 drivers/of/fdt.c:547: warning: expecting prototype for fdt_scan_reserved_mem(). Prototype was for __fdt_scan_reserved_mem() instead
 drivers/of/fdt.c:663: warning: Function parameter or member 'parent' not described in 'of_scan_flat_dt_subnodes'
 drivers/of/fdt.c:708: warning: Function parameter or member 'node' not described in 'of_get_flat_dt_prop'
 drivers/of/fdt.c:708: warning: Function parameter or member 'name' not described in 'of_get_flat_dt_prop'
 drivers/of/fdt.c:708: warning: Function parameter or member 'size' not described in 'of_get_flat_dt_prop'
 drivers/of/fdt.c:758: warning: Function parameter or member 'node' not described in 'of_flat_dt_match'
 drivers/of/fdt.c:758: warning: Function parameter or member 'compat' not described in 'of_flat_dt_match'
 drivers/of/fdt.c:778: warning: Function parameter or member 'node' not described in 'of_get_flat_dt_phandle'
 drivers/of/fdt.c:778: warning: expecting prototype for of_get_flat_dt_prop(). Prototype was for of_get_flat_dt_phandle() instead
 drivers/of/fdt.c:955: warning: Function parameter or member 'node' not described in 'early_init_dt_scan_root'
 drivers/of/fdt.c:955: warning: Function parameter or member 'uname' not described in 'early_init_dt_scan_root'
 drivers/of/fdt.c:955: warning: Function parameter or member 'depth' not described in 'early_init_dt_scan_root'
 drivers/of/fdt.c:955: warning: Function parameter or member 'data' not described in 'early_init_dt_scan_root'
 drivers/of/fdt.c:991: warning: Function parameter or member 'node' not described in 'early_init_dt_scan_memory'
 drivers/of/fdt.c:991: warning: Function parameter or member 'uname' not described in 'early_init_dt_scan_memory'
 drivers/of/fdt.c:991: warning: Function parameter or member 'depth' not described in 'early_init_dt_scan_memory'
 drivers/of/fdt.c:991: warning: Function parameter or member 'data' not described in 'early_init_dt_scan_memory'

Cc: Rob Herring <robh+dt@kernel.org>
Cc: Frank Rowand <frowand.list@gmail.com>
Cc: benh@kernel.crashing.org
Cc: devicetree@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/of/fdt.c | 23 ++++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)

diff --git a/drivers/of/fdt.c b/drivers/of/fdt.c
index dcc1dd96911a9..4d6d195e089aa 100644
--- a/drivers/of/fdt.c
+++ b/drivers/of/fdt.c
@@ -470,7 +470,7 @@ void *initial_boot_params __ro_after_init;
 
 static u32 of_fdt_crc32;
 
-/**
+/*
  * __reserved_mem_reserve_reg() - reserve all memory described in 'reg' property
  */
 static int __init __reserved_mem_reserve_reg(unsigned long node,
@@ -516,7 +516,7 @@ static int __init __reserved_mem_reserve_reg(unsigned long node,
 	return 0;
 }
 
-/**
+/*
  * __reserved_mem_check_root() - check if #size-cells, #address-cells provided
  * in /reserved-memory matches the values supported by the current implementation,
  * also check if ranges property has been provided
@@ -539,8 +539,8 @@ static int __init __reserved_mem_check_root(unsigned long node)
 	return 0;
 }
 
-/**
- * fdt_scan_reserved_mem() - scan a single FDT node for reserved memory
+/*
+ * __fdt_scan_reserved_mem() - scan a single FDT node for reserved memory
  */
 static int __init __fdt_scan_reserved_mem(unsigned long node, const char *uname,
 					  int depth, void *data)
@@ -650,6 +650,7 @@ int __init of_scan_flat_dt(int (*it)(unsigned long node,
 
 /**
  * of_scan_flat_dt_subnodes - scan sub-nodes of a node call callback on each.
+ * @parent: parent node
  * @it: callback function
  * @data: context data pointer
  *
@@ -689,7 +690,7 @@ int __init of_get_flat_dt_subnode_by_name(unsigned long node, const char *uname)
 	return fdt_subnode_offset(initial_boot_params, node, uname);
 }
 
-/**
+/*
  * of_get_flat_dt_root - find the root node in the flat blob
  */
 unsigned long __init of_get_flat_dt_root(void)
@@ -697,7 +698,7 @@ unsigned long __init of_get_flat_dt_root(void)
 	return 0;
 }
 
-/**
+/*
  * of_get_flat_dt_prop - Given a node in the flat blob, return the property ptr
  *
  * This function can be used within scan_flattened_dt callback to get
@@ -751,7 +752,7 @@ int __init of_flat_dt_is_compatible(unsigned long node, const char *compat)
 	return of_fdt_is_compatible(initial_boot_params, node, compat);
 }
 
-/**
+/*
  * of_flat_dt_match - Return true if node matches a list of compatible values
  */
 static int __init of_flat_dt_match(unsigned long node, const char *const *compat)
@@ -771,8 +772,8 @@ static int __init of_flat_dt_match(unsigned long node, const char *const *compat
 	return score;
 }
 
-/**
- * of_get_flat_dt_prop - Given a node in the flat blob, return the phandle
+/*
+ * of_get_flat_dt_phandle - Given a node in the flat blob, return the phandle
  */
 uint32_t __init of_get_flat_dt_phandle(unsigned long node)
 {
@@ -947,7 +948,7 @@ int __init early_init_dt_scan_chosen_stdout(void)
 }
 #endif
 
-/**
+/*
  * early_init_dt_scan_root - fetch the top level address and size cells
  */
 int __init early_init_dt_scan_root(unsigned long node, const char *uname,
@@ -983,7 +984,7 @@ u64 __init dt_mem_next_cell(int s, const __be32 **cellp)
 	return of_read_number(p, s);
 }
 
-/**
+/*
  * early_init_dt_scan_memory - Look for and parse memory nodes
  */
 int __init early_init_dt_scan_memory(unsigned long node, const char *uname,
-- 
2.27.0

[PATCH 08/10] of: of_net: Provide function name and param description

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/of/of_net.c:104: warning: Function parameter or member 'np' not described in 'of_get_mac_address'
 drivers/of/of_net.c:104: warning: expecting prototype for mac(). Prototype was for of_get_mac_address() instead

Cc: Andrew Lunn <andrew@lunn.ch>
Cc: Heiner Kallweit <hkallweit1@gmail.com>
Cc: Russell King <linux@armlinux.org.uk>
Cc: Rob Herring <robh+dt@kernel.org>
Cc: Frank Rowand <frowand.list@gmail.com>
Cc: netdev@vger.kernel.org
Cc: devicetree@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/of/of_net.c | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/drivers/of/of_net.c b/drivers/of/of_net.c
index 6e411821583e4..bc0a27de69d4c 100644
--- a/drivers/of/of_net.c
+++ b/drivers/of/of_net.c
@@ -79,6 +79,9 @@ static const void *of_get_mac_addr_nvmem(struct device_node *np)
 }
 
 /**
+ * of_get_mac_address()
+ * @np:		Caller's Device Node
+ *
  * Search the device tree for the best MAC address to use.  'mac-address' is
  * checked first, because that is supposed to contain to "most recent" MAC
  * address. If that isn't set, then 'local-mac-address' is checked next,
-- 
2.27.0

Re: [PATCH 08/10] of: of_net: Provide function name and param description

[Andrew Lunn]

On Thu, Mar 18, 2021 at 10:40:34AM +0000, Lee Jones wrote:
> Fixes the following W=1 kernel build warning(s):
> 
>  drivers/of/of_net.c:104: warning: Function parameter or member 'np' not described in 'of_get_mac_address'
>  drivers/of/of_net.c:104: warning: expecting prototype for mac(). Prototype was for of_get_mac_address() instead
> 
> Cc: Andrew Lunn <andrew@lunn.ch>
> Cc: Heiner Kallweit <hkallweit1@gmail.com>
> Cc: Russell King <linux@armlinux.org.uk>
> Cc: Rob Herring <robh+dt@kernel.org>
> Cc: Frank Rowand <frowand.list@gmail.com>
> Cc: netdev@vger.kernel.org
> Cc: devicetree@vger.kernel.org
> Signed-off-by: Lee Jones <lee.jones@linaro.org>

Thanks for fixing it up.

Reviewed-by: Andrew Lunn <andrew@lunn.ch>

    Andrew

[PATCH 09/10] of: overlay: Fix function name disparity

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/of/overlay.c:147: warning: expecting prototype for of_overlay_notifier_register(). Prototype was for of_overlay_notifier_unregister() instead

Cc: Pantelis Antoniou <pantelis.antoniou@konsulko.com>
Cc: Frank Rowand <frowand.list@gmail.com>
Cc: Rob Herring <robh+dt@kernel.org>
Cc: devicetree@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/of/overlay.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/of/overlay.c b/drivers/of/overlay.c
index 50bbe0edf5380..1c867a5e4c7c2 100644
--- a/drivers/of/overlay.c
+++ b/drivers/of/overlay.c
@@ -140,7 +140,7 @@ int of_overlay_notifier_register(struct notifier_block *nb)
 EXPORT_SYMBOL_GPL(of_overlay_notifier_register);
 
 /**
- * of_overlay_notifier_register() - Unregister notifier for overlay operations
+ * of_overlay_notifier_unregister() - Unregister notifier for overlay operations
  * @nb:		Notifier block to unregister
  */
 int of_overlay_notifier_unregister(struct notifier_block *nb)
-- 
2.27.0

[PATCH 10/10] of: of_reserved_mem: Demote kernel-doc abuses

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/of/of_reserved_mem.c:53: warning: Function parameter or member 'node' not described in 'fdt_reserved_mem_save_node'
 drivers/of/of_reserved_mem.c:53: warning: Function parameter or member 'uname' not described in 'fdt_reserved_mem_save_node'
 drivers/of/of_reserved_mem.c:53: warning: Function parameter or member 'base' not described in 'fdt_reserved_mem_save_node'
 drivers/of/of_reserved_mem.c:53: warning: Function parameter or member 'size' not described in 'fdt_reserved_mem_save_node'
 drivers/of/of_reserved_mem.c:76: warning: Function parameter or member 'node' not described in '__reserved_mem_alloc_size'
 drivers/of/of_reserved_mem.c:76: warning: Function parameter or member 'uname' not described in '__reserved_mem_alloc_size'
 drivers/of/of_reserved_mem.c:76: warning: Function parameter or member 'res_base' not described in '__reserved_mem_alloc_size'
 drivers/of/of_reserved_mem.c:76: warning: Function parameter or member 'res_size' not described in '__reserved_mem_alloc_size'
 drivers/of/of_reserved_mem.c:171: warning: Function parameter or member 'rmem' not described in '__reserved_mem_init_node'

Cc: Rob Herring <robh+dt@kernel.org>
Cc: Frank Rowand <frowand.list@gmail.com>
Cc: Marek Szyprowski <m.szyprowski@samsung.com>
Cc: Josh Cartwright <joshc@codeaurora.org>
Cc: devicetree@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/of/of_reserved_mem.c | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/drivers/of/of_reserved_mem.c b/drivers/of/of_reserved_mem.c
index a7fbc5e37e19e..15e2417974d67 100644
--- a/drivers/of/of_reserved_mem.c
+++ b/drivers/of/of_reserved_mem.c
@@ -45,7 +45,7 @@ static int __init early_init_dt_alloc_reserved_memory_arch(phys_addr_t size,
 	return memblock_reserve(base, size);
 }
 
-/**
+/*
  * fdt_reserved_mem_save_node() - save fdt node for second pass initialization
  */
 void __init fdt_reserved_mem_save_node(unsigned long node, const char *uname,
@@ -67,7 +67,7 @@ void __init fdt_reserved_mem_save_node(unsigned long node, const char *uname,
 	return;
 }
 
-/**
+/*
  * __reserved_mem_alloc_size() - allocate reserved memory described by
  *	'size', 'alignment'  and 'alloc-ranges' properties.
  */
@@ -164,7 +164,7 @@ static int __init __reserved_mem_alloc_size(unsigned long node,
 static const struct of_device_id __rmem_of_table_sentinel
 	__used __section("__reservedmem_of_table_end");
 
-/**
+/*
  * __reserved_mem_init_node() - call region specific reserved memory init code
  */
 static int __init __reserved_mem_init_node(struct reserved_mem *rmem)
-- 
2.27.0

Re: [PATCH v2 00/10] Rid W=1 warnings from OF

[Rob Herring]

On Thu, Mar 18, 2021 at 4:40 AM Lee Jones <lee.jones@linaro.org> wrote:
>
> This set is part of a larger effort attempting to clean-up W=1
> kernel builds, which are currently overwhelmingly riddled with
> niggly little warnings.
>
> v2:
>  - Provided some descriptions to exported functions
>
> Lee Jones (10):
>   of: device: Fix function name in header and provide missing
>     descriptions
>   of: dynamic: Fix incorrect parameter name and provide missing
>     descriptions
>   of: platform: Demote kernel-doc abuse
>   of: base: Fix some formatting issues and provide missing descriptions
>   of: property: Provide missing member description and remove excess
>     param
>   of: address: Provide descriptions for 'of_address_to_resource's params
>   of: fdt: Demote kernel-doc abuses and fix function naming
>   of: of_net: Provide function name and param description
>   of: overlay: Fix function name disparity
>   of: of_reserved_mem: Demote kernel-doc abuses
>
>  drivers/of/address.c         |  3 +++
>  drivers/of/base.c            | 16 +++++++++++-----
>  drivers/of/device.c          |  7 ++++++-
>  drivers/of/dynamic.c         |  4 +++-
>  drivers/of/fdt.c             | 23 ++++++++++++-----------
>  drivers/of/of_net.c          |  3 +++
>  drivers/of/of_reserved_mem.c |  6 +++---
>  drivers/of/overlay.c         |  2 +-
>  drivers/of/platform.c        |  2 +-
>  drivers/of/property.c        |  2 +-
>  10 files changed, 44 insertions(+), 24 deletions(-)

I still see some warnings (note this is with DT files added to doc
build). Can you send follow-up patches:

../include/linux/of.h:1193: warning: Function parameter or member
'output' not described in 'of_property_read_string_index'
../include/linux/of.h:1193: warning: Excess function parameter
'out_string' description in 'of_property_read_string_index'
../include/linux/of.h:1461: warning: cannot understand function
prototype: 'enum of_overlay_notify_action '
../drivers/of/base.c:1781: warning: Excess function parameter 'prob'
description in '__of_add_property'
../drivers/of/base.c:1804: warning: Excess function parameter 'prob'
description in 'of_add_property'
../drivers/of/base.c:1855: warning: Function parameter or member
'prop' not described in 'of_remove_property'
../drivers/of/base.c:1855: warning: Excess function parameter 'prob'
description in 'of_remove_property'

BTW, there some more which I guess W=1 doesn't find:

/home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
../drivers/of/base.c:906: WARNING: Block quote ends without a blank
line; unexpected unindent.
/home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
../drivers/of/base.c:1465: WARNING: Definition list ends without a
blank line; unexpected unindent.
/home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
../drivers/of/base.c:1469: WARNING: Definition list ends without a
blank line; unexpected unindent.
/home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
../drivers/of/base.c:1473: WARNING: Definition list ends without a
blank line; unexpected unindent.
/home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
../drivers/of/base.c:1517: WARNING: Definition list ends without a
blank line; unexpected unindent.
/home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
../drivers/of/base.c:1521: WARNING: Definition list ends without a
blank line; unexpected unindent.
/home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
../drivers/of/base.c:1526: WARNING: Unexpected indentation.
/home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
../drivers/of/base.c:1528: WARNING: Block quote ends without a blank
line; unexpected unindent.
/home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
../drivers/of/base.c:1529: WARNING: Definition list ends without a
blank line; unexpected unindent.
/home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
../drivers/of/base.c:1533: WARNING: Definition list ends without a
blank line; unexpected unindent.
/home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
../drivers/of/base.c:1705: WARNING: Definition list ends without a
blank line; unexpected unindent.
/home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:49:
../drivers/of/overlay.c:1183: WARNING: Inline emphasis start-string
without end-string.

Rob

Re: [PATCH v2 00/10] Rid W=1 warnings from OF

[Lee Jones]

On Mon, 22 Mar 2021, Rob Herring wrote:

> On Thu, Mar 18, 2021 at 4:40 AM Lee Jones <lee.jones@linaro.org> wrote:
> >
> > This set is part of a larger effort attempting to clean-up W=1
> > kernel builds, which are currently overwhelmingly riddled with
> > niggly little warnings.
> >
> > v2:
> >  - Provided some descriptions to exported functions
> >
> > Lee Jones (10):
> >   of: device: Fix function name in header and provide missing
> >     descriptions
> >   of: dynamic: Fix incorrect parameter name and provide missing
> >     descriptions
> >   of: platform: Demote kernel-doc abuse
> >   of: base: Fix some formatting issues and provide missing descriptions
> >   of: property: Provide missing member description and remove excess
> >     param
> >   of: address: Provide descriptions for 'of_address_to_resource's params
> >   of: fdt: Demote kernel-doc abuses and fix function naming
> >   of: of_net: Provide function name and param description
> >   of: overlay: Fix function name disparity
> >   of: of_reserved_mem: Demote kernel-doc abuses
> >
> >  drivers/of/address.c         |  3 +++
> >  drivers/of/base.c            | 16 +++++++++++-----
> >  drivers/of/device.c          |  7 ++++++-
> >  drivers/of/dynamic.c         |  4 +++-
> >  drivers/of/fdt.c             | 23 ++++++++++++-----------
> >  drivers/of/of_net.c          |  3 +++
> >  drivers/of/of_reserved_mem.c |  6 +++---
> >  drivers/of/overlay.c         |  2 +-
> >  drivers/of/platform.c        |  2 +-
> >  drivers/of/property.c        |  2 +-
> >  10 files changed, 44 insertions(+), 24 deletions(-)
> 
> I still see some warnings (note this is with DT files added to doc
> build). Can you send follow-up patches:
> 
> ../include/linux/of.h:1193: warning: Function parameter or member
> 'output' not described in 'of_property_read_string_index'
> ../include/linux/of.h:1193: warning: Excess function parameter
> 'out_string' description in 'of_property_read_string_index'
> ../include/linux/of.h:1461: warning: cannot understand function
> prototype: 'enum of_overlay_notify_action '
> ../drivers/of/base.c:1781: warning: Excess function parameter 'prob'
> description in '__of_add_property'
> ../drivers/of/base.c:1804: warning: Excess function parameter 'prob'
> description in 'of_add_property'
> ../drivers/of/base.c:1855: warning: Function parameter or member
> 'prop' not described in 'of_remove_property'
> ../drivers/of/base.c:1855: warning: Excess function parameter 'prob'
> description in 'of_remove_property'

You don't want much do you! ;)

Sure, I plan to clean up all of the kernel with subsequent patches.

> BTW, there some more which I guess W=1 doesn't find:
> 
> /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> ../drivers/of/base.c:906: WARNING: Block quote ends without a blank
> line; unexpected unindent.
> /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> ../drivers/of/base.c:1465: WARNING: Definition list ends without a
> blank line; unexpected unindent.
> /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> ../drivers/of/base.c:1469: WARNING: Definition list ends without a
> blank line; unexpected unindent.
> /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> ../drivers/of/base.c:1473: WARNING: Definition list ends without a
> blank line; unexpected unindent.
> /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> ../drivers/of/base.c:1517: WARNING: Definition list ends without a
> blank line; unexpected unindent.
> /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> ../drivers/of/base.c:1521: WARNING: Definition list ends without a
> blank line; unexpected unindent.
> /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> ../drivers/of/base.c:1526: WARNING: Unexpected indentation.
> /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> ../drivers/of/base.c:1528: WARNING: Block quote ends without a blank
> line; unexpected unindent.
> /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> ../drivers/of/base.c:1529: WARNING: Definition list ends without a
> blank line; unexpected unindent.
> /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> ../drivers/of/base.c:1533: WARNING: Definition list ends without a
> blank line; unexpected unindent.
> /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> ../drivers/of/base.c:1705: WARNING: Definition list ends without a
> blank line; unexpected unindent.
> /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:49:
> ../drivers/of/overlay.c:1183: WARNING: Inline emphasis start-string
> without end-string.

What command did you use to find these?

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog

Re: [PATCH v2 00/10] Rid W=1 warnings from OF

[Rob Herring]

On Tue, Mar 23, 2021 at 2:36 AM Lee Jones <lee.jones@linaro.org> wrote:
>
> On Mon, 22 Mar 2021, Rob Herring wrote:
>
> > On Thu, Mar 18, 2021 at 4:40 AM Lee Jones <lee.jones@linaro.org> wrote:
> > >
> > > This set is part of a larger effort attempting to clean-up W=1
> > > kernel builds, which are currently overwhelmingly riddled with
> > > niggly little warnings.
> > >
> > > v2:
> > >  - Provided some descriptions to exported functions
> > >
> > > Lee Jones (10):
> > >   of: device: Fix function name in header and provide missing
> > >     descriptions
> > >   of: dynamic: Fix incorrect parameter name and provide missing
> > >     descriptions
> > >   of: platform: Demote kernel-doc abuse
> > >   of: base: Fix some formatting issues and provide missing descriptions
> > >   of: property: Provide missing member description and remove excess
> > >     param
> > >   of: address: Provide descriptions for 'of_address_to_resource's params
> > >   of: fdt: Demote kernel-doc abuses and fix function naming
> > >   of: of_net: Provide function name and param description
> > >   of: overlay: Fix function name disparity
> > >   of: of_reserved_mem: Demote kernel-doc abuses
> > >
> > >  drivers/of/address.c         |  3 +++
> > >  drivers/of/base.c            | 16 +++++++++++-----
> > >  drivers/of/device.c          |  7 ++++++-
> > >  drivers/of/dynamic.c         |  4 +++-
> > >  drivers/of/fdt.c             | 23 ++++++++++++-----------
> > >  drivers/of/of_net.c          |  3 +++
> > >  drivers/of/of_reserved_mem.c |  6 +++---
> > >  drivers/of/overlay.c         |  2 +-
> > >  drivers/of/platform.c        |  2 +-
> > >  drivers/of/property.c        |  2 +-
> > >  10 files changed, 44 insertions(+), 24 deletions(-)
> >
> > I still see some warnings (note this is with DT files added to doc
> > build). Can you send follow-up patches:
> >
> > ../include/linux/of.h:1193: warning: Function parameter or member
> > 'output' not described in 'of_property_read_string_index'
> > ../include/linux/of.h:1193: warning: Excess function parameter
> > 'out_string' description in 'of_property_read_string_index'
> > ../include/linux/of.h:1461: warning: cannot understand function
> > prototype: 'enum of_overlay_notify_action '
> > ../drivers/of/base.c:1781: warning: Excess function parameter 'prob'
> > description in '__of_add_property'
> > ../drivers/of/base.c:1804: warning: Excess function parameter 'prob'
> > description in 'of_add_property'
> > ../drivers/of/base.c:1855: warning: Function parameter or member
> > 'prop' not described in 'of_remove_property'
> > ../drivers/of/base.c:1855: warning: Excess function parameter 'prob'
> > description in 'of_remove_property'
>
> You don't want much do you! ;)

Hey, want to fix all the schema warnings for me? ;)

>
> Sure, I plan to clean up all of the kernel with subsequent patches.
>
> > BTW, there some more which I guess W=1 doesn't find:
> >
> > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > ../drivers/of/base.c:906: WARNING: Block quote ends without a blank
> > line; unexpected unindent.
> > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > ../drivers/of/base.c:1465: WARNING: Definition list ends without a
> > blank line; unexpected unindent.
> > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > ../drivers/of/base.c:1469: WARNING: Definition list ends without a
> > blank line; unexpected unindent.
> > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > ../drivers/of/base.c:1473: WARNING: Definition list ends without a
> > blank line; unexpected unindent.
> > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > ../drivers/of/base.c:1517: WARNING: Definition list ends without a
> > blank line; unexpected unindent.
> > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > ../drivers/of/base.c:1521: WARNING: Definition list ends without a
> > blank line; unexpected unindent.
> > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > ../drivers/of/base.c:1526: WARNING: Unexpected indentation.
> > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > ../drivers/of/base.c:1528: WARNING: Block quote ends without a blank
> > line; unexpected unindent.
> > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > ../drivers/of/base.c:1529: WARNING: Definition list ends without a
> > blank line; unexpected unindent.
> > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > ../drivers/of/base.c:1533: WARNING: Definition list ends without a
> > blank line; unexpected unindent.
> > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > ../drivers/of/base.c:1705: WARNING: Definition list ends without a
> > blank line; unexpected unindent.
> > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:49:
> > ../drivers/of/overlay.c:1183: WARNING: Inline emphasis start-string
> > without end-string.
>
> What command did you use to find these?

make htmldocs

(with the DT files added to the docs)

These turn out to be the tip of the iceberg. There's all sorts of
formatting issues. Tabs are a problem and the 'Return' section is
wrong. These are only found looking at the output.

Rob

Re: [PATCH v2 00/10] Rid W=1 warnings from OF

[Lee Jones]

On Wed, 24 Mar 2021, Rob Herring wrote:

> On Tue, Mar 23, 2021 at 2:36 AM Lee Jones <lee.jones@linaro.org> wrote:
> >
> > On Mon, 22 Mar 2021, Rob Herring wrote:
> >
> > > On Thu, Mar 18, 2021 at 4:40 AM Lee Jones <lee.jones@linaro.org> wrote:
> > > >
> > > > This set is part of a larger effort attempting to clean-up W=1
> > > > kernel builds, which are currently overwhelmingly riddled with
> > > > niggly little warnings.
> > > >
> > > > v2:
> > > >  - Provided some descriptions to exported functions
> > > >
> > > > Lee Jones (10):
> > > >   of: device: Fix function name in header and provide missing
> > > >     descriptions
> > > >   of: dynamic: Fix incorrect parameter name and provide missing
> > > >     descriptions
> > > >   of: platform: Demote kernel-doc abuse
> > > >   of: base: Fix some formatting issues and provide missing descriptions
> > > >   of: property: Provide missing member description and remove excess
> > > >     param
> > > >   of: address: Provide descriptions for 'of_address_to_resource's params
> > > >   of: fdt: Demote kernel-doc abuses and fix function naming
> > > >   of: of_net: Provide function name and param description
> > > >   of: overlay: Fix function name disparity
> > > >   of: of_reserved_mem: Demote kernel-doc abuses
> > > >
> > > >  drivers/of/address.c         |  3 +++
> > > >  drivers/of/base.c            | 16 +++++++++++-----
> > > >  drivers/of/device.c          |  7 ++++++-
> > > >  drivers/of/dynamic.c         |  4 +++-
> > > >  drivers/of/fdt.c             | 23 ++++++++++++-----------
> > > >  drivers/of/of_net.c          |  3 +++
> > > >  drivers/of/of_reserved_mem.c |  6 +++---
> > > >  drivers/of/overlay.c         |  2 +-
> > > >  drivers/of/platform.c        |  2 +-
> > > >  drivers/of/property.c        |  2 +-
> > > >  10 files changed, 44 insertions(+), 24 deletions(-)
> > >
> > > I still see some warnings (note this is with DT files added to doc
> > > build). Can you send follow-up patches:
> > >
> > > ../include/linux/of.h:1193: warning: Function parameter or member
> > > 'output' not described in 'of_property_read_string_index'
> > > ../include/linux/of.h:1193: warning: Excess function parameter
> > > 'out_string' description in 'of_property_read_string_index'
> > > ../include/linux/of.h:1461: warning: cannot understand function
> > > prototype: 'enum of_overlay_notify_action '
> > > ../drivers/of/base.c:1781: warning: Excess function parameter 'prob'
> > > description in '__of_add_property'
> > > ../drivers/of/base.c:1804: warning: Excess function parameter 'prob'
> > > description in 'of_add_property'
> > > ../drivers/of/base.c:1855: warning: Function parameter or member
> > > 'prop' not described in 'of_remove_property'
> > > ../drivers/of/base.c:1855: warning: Excess function parameter 'prob'
> > > description in 'of_remove_property'
> >
> > You don't want much do you! ;)
> 
> Hey, want to fix all the schema warnings for me? ;)

Definitely not.  I've even gone to the trouble of disabling them. :D

> > Sure, I plan to clean up all of the kernel with subsequent patches.
> >
> > > BTW, there some more which I guess W=1 doesn't find:
> > >
> > > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > > ../drivers/of/base.c:906: WARNING: Block quote ends without a blank
> > > line; unexpected unindent.
> > > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > > ../drivers/of/base.c:1465: WARNING: Definition list ends without a
> > > blank line; unexpected unindent.
> > > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > > ../drivers/of/base.c:1469: WARNING: Definition list ends without a
> > > blank line; unexpected unindent.
> > > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > > ../drivers/of/base.c:1473: WARNING: Definition list ends without a
> > > blank line; unexpected unindent.
> > > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > > ../drivers/of/base.c:1517: WARNING: Definition list ends without a
> > > blank line; unexpected unindent.
> > > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > > ../drivers/of/base.c:1521: WARNING: Definition list ends without a
> > > blank line; unexpected unindent.
> > > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > > ../drivers/of/base.c:1526: WARNING: Unexpected indentation.
> > > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > > ../drivers/of/base.c:1528: WARNING: Block quote ends without a blank
> > > line; unexpected unindent.
> > > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > > ../drivers/of/base.c:1529: WARNING: Definition list ends without a
> > > blank line; unexpected unindent.
> > > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > > ../drivers/of/base.c:1533: WARNING: Definition list ends without a
> > > blank line; unexpected unindent.
> > > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:19:
> > > ../drivers/of/base.c:1705: WARNING: Definition list ends without a
> > > blank line; unexpected unindent.
> > > /home/rob/proj/git/linux-dt/Documentation/driver-api/devicetree:49:
> > > ../drivers/of/overlay.c:1183: WARNING: Inline emphasis start-string
> > > without end-string.
> >
> > What command did you use to find these?
> 
> make htmldocs
> 
> (with the DT files added to the docs)
> 
> These turn out to be the tip of the iceberg. There's all sorts of
> formatting issues. Tabs are a problem and the 'Return' section is
> wrong. These are only found looking at the output.

Heh!  Depends how desperate I get. :'D

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog

[PATCH 00/10] Rid W=1 warnings from OF

[Lee Jones]

This set is part of a larger effort attempting to clean-up W=1
kernel builds, which are currently overwhelmingly riddled with
niggly little warnings.

Lee Jones (10):
  of: device: Fix function name in header and demote kernel-doc abuse
  of: dynamic: Fix incorrect parameter name and demote kernel-doc abuse
  of: platform: Demote kernel-doc abuse
  of: base: Fix some formatting issues and demote non-conformant
    kernel-doc headers
  of: property: Provide missing member description and remove excess
    param
  of: address: Demote non-conformant kernel-doc header
  of: fdt: Demote kernel-doc abuses
  of: of_net: Demote non-conforming kernel-doc header
  of: overlay: Fix function name disparity
  of: of_reserved_mem: Demote kernel-doc abuses

 drivers/of/address.c         |  2 +-
 drivers/of/base.c            | 16 ++++++++--------
 drivers/of/device.c          |  6 +++---
 drivers/of/dynamic.c         |  6 +++---
 drivers/of/fdt.c             | 19 ++++++++++---------
 drivers/of/of_net.c          |  2 +-
 drivers/of/of_reserved_mem.c |  6 +++---
 drivers/of/overlay.c         |  2 +-
 drivers/of/platform.c        |  2 +-
 drivers/of/property.c        |  2 +-
 10 files changed, 32 insertions(+), 31 deletions(-)

Cc: Andrew Lunn <andrew@lunn.ch>
Cc: Anton Vorontsov <anton@enomsg.org>
Cc: benh@kernel.crashing.org
Cc: Colin Cross <ccross@android.com>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: devicetree@vger.kernel.org
Cc: Frank Rowand <frowand.list@gmail.com>
Cc: Heiner Kallweit <hkallweit1@gmail.com>
Cc: Josh Cartwright <joshc@codeaurora.org>
Cc: Kees Cook <keescook@chromium.org>
Cc: Marek Szyprowski <m.szyprowski@samsung.com>
Cc: netdev@vger.kernel.org
Cc: Pantelis Antoniou <pantelis.antoniou@konsulko.com>
Cc: Rob Herring <robh+dt@kernel.org>
Cc: Russell King <linux@armlinux.org.uk>
Cc: Tony Luck <tony.luck@intel.com>
-- 
2.27.0

[PATCH 03/10] of: platform: Demote kernel-doc abuse

[Lee Jones]

Fixes the following W=1 kernel build warning(s):

 drivers/of/platform.c:298: warning: Function parameter or member 'lookup' not described in 'of_dev_lookup'
 drivers/of/platform.c:298: warning: Function parameter or member 'np' not described in 'of_dev_lookup'

Cc: Rob Herring <robh+dt@kernel.org>
Cc: Frank Rowand <frowand.list@gmail.com>
Cc: Kees Cook <keescook@chromium.org>
Cc: Anton Vorontsov <anton@enomsg.org>
Cc: Colin Cross <ccross@android.com>
Cc: Tony Luck <tony.luck@intel.com>
Cc: benh@kernel.crashing.org
Cc: devicetree@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>
---
 drivers/of/platform.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/of/platform.c b/drivers/of/platform.c
index 0da86209ddaab..0ed46d301431b 100644
--- a/drivers/of/platform.c
+++ b/drivers/of/platform.c
@@ -290,7 +290,7 @@ static struct amba_device *of_amba_device_create(struct device_node *node,
 }
 #endif /* CONFIG_ARM_AMBA */
 
-/**
+/*
  * of_dev_lookup() - Given a device node, lookup the preferred Linux name
  */
 static const struct of_dev_auxdata *of_dev_lookup(const struct of_dev_auxdata *lookup,
-- 
2.27.0