[PATCH v3] software_node: Add kernel-doc comments to exported symbols

[PATCH v3] software_node: Add kernel-doc comments to exported symbols

[Daniel Scally]

A number of functions which are exported via EXPORT_SYMBOL_GPL() lack any
kernel-doc comments; add those in so all exported symbols are documented.

Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Reviewed-by: Heikki Krogerus <heikki.krogerus@linux.intel.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Signed-off-by: Daniel Scally <djrscally@gmail.com>
---
Changelog for v3:

	- s/passed to @parent/passed as @parent
	- Wrapped a long summary line - TIL that you can do that, thanks
	  Sakari

 drivers/base/swnode.c | 54 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/drivers/base/swnode.c b/drivers/base/swnode.c
index 4a4b2008fbc2..39fbb653c58a 100644
--- a/drivers/base/swnode.c
+++ b/drivers/base/swnode.c
@@ -33,6 +33,13 @@ static struct kset *swnode_kset;
 
 static const struct fwnode_operations software_node_ops;
 
+/**
+ * is_software_node() - check if given fwnode was created from a software_node
+ * @fwnode: The &struct fwnode_handle to check
+ *
+ * This function is used to check whether a given firmware node handle was
+ * created by registering a &struct software_node or not.
+ */
 bool is_software_node(const struct fwnode_handle *fwnode)
 {
 	return !IS_ERR_OR_NULL(fwnode) && fwnode->ops == &software_node_ops;
@@ -71,6 +78,15 @@ software_node_to_swnode(const struct software_node *node)
 	return swnode;
 }
 
+/**
+ * to_software_node() - Fetch the software node used to create a firmware
+ *			node handle
+ * @fwnode: The pointer to a &struct fwnode_handle to parse
+ *
+ * This function attempts to fetch a pointer to the &struct software_node which
+ * was used to create the given @fwnode. Note that this will only work if the
+ * software node has **not** been released.
+ */
 const struct software_node *to_software_node(const struct fwnode_handle *fwnode)
 {
 	const struct swnode *swnode = to_swnode(fwnode);
@@ -79,6 +95,14 @@ const struct software_node *to_software_node(const struct fwnode_handle *fwnode)
 }
 EXPORT_SYMBOL_GPL(to_software_node);
 
+/**
+ * software_node_fwnode() - Fetch firmware node associated with a given software node
+ * @node: The pointer to a &struct software_node to parse
+ *
+ * This function attempts to fetch a pointer to the &struct fwnode_handle which
+ * was created from the given @node. Note that this will only work after the
+ * software node has been registered.
+ */
 struct fwnode_handle *software_node_fwnode(const struct software_node *node)
 {
 	struct swnode *swnode = software_node_to_swnode(node);
@@ -800,6 +824,27 @@ void software_node_unregister(const struct software_node *node)
 }
 EXPORT_SYMBOL_GPL(software_node_unregister);
 
+/**
+ * fwnode_create_software_node() - Create and register a new software_node
+ * @properties: NULL terminated array of properties to assign to the new node
+ * @parent: Pointer to a &struct fwnode_handle to assign as parent to the new
+ *	    node
+ *
+ * NOTE: The pointer passed as @parent **must** be to a firmware node handle
+ * that was created by registering a software node, meaning is_software_node()
+ * must return true when passed that pointer.
+ *
+ * This function creates a new instance of &struct software_node, assigns it a
+ * copy of the given array of properties and registers it as a new fwnode_handle.
+ * Freeing of the allocated memory when the fwnode_handle is no longer needed is
+ * handled via software_node_release() and does not need to be done separately.
+ *
+ * Returns:
+ * * fwnode_handle *	- On success
+ * * -EINVAL		- When @parent is not associated with a software_node
+ * * -ENOMEM		- When memory allocation fails
+ * * -Other		- Propagated errors from sub-functions
+ */
 struct fwnode_handle *
 fwnode_create_software_node(const struct property_entry *properties,
 			    const struct fwnode_handle *parent)
@@ -832,6 +877,15 @@ fwnode_create_software_node(const struct property_entry *properties,
 }
 EXPORT_SYMBOL_GPL(fwnode_create_software_node);
 
+/**
+ * fwnode_remove_software_node() - Put a reference to a registered software_node
+ * @fwnode: The pointer to the &struct fwnode_handle you want to release
+ *
+ * Release a reference to a registered &struct software_node. This function
+ * differs from software_node_put() in that it takes no action if the
+ * firmware node handle passed to @fwnode turns out not to have been created by
+ * registering a software_node.
+ */
 void fwnode_remove_software_node(struct fwnode_handle *fwnode)
 {
 	struct swnode *swnode = to_swnode(fwnode);
-- 
2.25.1

Re: [PATCH v3] software_node: Add kernel-doc comments to exported symbols

[Sakari Ailus]

Hi Dan,

On Wed, Jan 20, 2021 at 12:03:39AM +0000, Daniel Scally wrote:
> A number of functions which are exported via EXPORT_SYMBOL_GPL() lack any
> kernel-doc comments; add those in so all exported symbols are documented.
> 
> Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> Reviewed-by: Heikki Krogerus <heikki.krogerus@linux.intel.com>
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> Reviewed-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> Signed-off-by: Daniel Scally <djrscally@gmail.com>
> ---
> Changelog for v3:
> 
> 	- s/passed to @parent/passed as @parent
> 	- Wrapped a long summary line - TIL that you can do that, thanks
> 	  Sakari
> 
>  drivers/base/swnode.c | 54 +++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 54 insertions(+)
> 
> diff --git a/drivers/base/swnode.c b/drivers/base/swnode.c
> index 4a4b2008fbc2..39fbb653c58a 100644
> --- a/drivers/base/swnode.c
> +++ b/drivers/base/swnode.c
> @@ -33,6 +33,13 @@ static struct kset *swnode_kset;
>  
>  static const struct fwnode_operations software_node_ops;
>  
> +/**
> + * is_software_node() - check if given fwnode was created from a software_node
> + * @fwnode: The &struct fwnode_handle to check
> + *
> + * This function is used to check whether a given firmware node handle was
> + * created by registering a &struct software_node or not.
> + */
>  bool is_software_node(const struct fwnode_handle *fwnode)
>  {
>  	return !IS_ERR_OR_NULL(fwnode) && fwnode->ops == &software_node_ops;
> @@ -71,6 +78,15 @@ software_node_to_swnode(const struct software_node *node)
>  	return swnode;
>  }
>  
> +/**
> + * to_software_node() - Fetch the software node used to create a firmware
> + *			node handle
> + * @fwnode: The pointer to a &struct fwnode_handle to parse
> + *
> + * This function attempts to fetch a pointer to the &struct software_node which
> + * was used to create the given @fwnode. Note that this will only work if the
> + * software node has **not** been released.
> + */
>  const struct software_node *to_software_node(const struct fwnode_handle *fwnode)
>  {
>  	const struct swnode *swnode = to_swnode(fwnode);
> @@ -79,6 +95,14 @@ const struct software_node *to_software_node(const struct fwnode_handle *fwnode)
>  }
>  EXPORT_SYMBOL_GPL(to_software_node);
>  
> +/**
> + * software_node_fwnode() - Fetch firmware node associated with a given software node
> + * @node: The pointer to a &struct software_node to parse
> + *
> + * This function attempts to fetch a pointer to the &struct fwnode_handle which
> + * was created from the given @node. Note that this will only work after the
> + * software node has been registered.
> + */
>  struct fwnode_handle *software_node_fwnode(const struct software_node *node)
>  {
>  	struct swnode *swnode = software_node_to_swnode(node);
> @@ -800,6 +824,27 @@ void software_node_unregister(const struct software_node *node)
>  }
>  EXPORT_SYMBOL_GPL(software_node_unregister);
>  
> +/**
> + * fwnode_create_software_node() - Create and register a new software_node
> + * @properties: NULL terminated array of properties to assign to the new node
> + * @parent: Pointer to a &struct fwnode_handle to assign as parent to the new
> + *	    node
> + *
> + * NOTE: The pointer passed as @parent **must** be to a firmware node handle
> + * that was created by registering a software node, meaning is_software_node()
> + * must return true when passed that pointer.
> + *
> + * This function creates a new instance of &struct software_node, assigns it a
> + * copy of the given array of properties and registers it as a new fwnode_handle.
> + * Freeing of the allocated memory when the fwnode_handle is no longer needed is
> + * handled via software_node_release() and does not need to be done separately.

Please wrap all lines over 80 unless there's a reason to keep them longer.

> + *
> + * Returns:
> + * * fwnode_handle *	- On success
> + * * -EINVAL		- When @parent is not associated with a software_node
> + * * -ENOMEM		- When memory allocation fails
> + * * -Other		- Propagated errors from sub-functions
> + */
>  struct fwnode_handle *
>  fwnode_create_software_node(const struct property_entry *properties,
>  			    const struct fwnode_handle *parent)
> @@ -832,6 +877,15 @@ fwnode_create_software_node(const struct property_entry *properties,
>  }
>  EXPORT_SYMBOL_GPL(fwnode_create_software_node);
>  
> +/**
> + * fwnode_remove_software_node() - Put a reference to a registered software_node
> + * @fwnode: The pointer to the &struct fwnode_handle you want to release
> + *
> + * Release a reference to a registered &struct software_node. This function
> + * differs from software_node_put() in that it takes no action if the
> + * firmware node handle passed to @fwnode turns out not to have been created by
> + * registering a software_node.
> + */
>  void fwnode_remove_software_node(struct fwnode_handle *fwnode)
>  {
>  	struct swnode *swnode = to_swnode(fwnode);
> -- 
> 2.25.1
> 

-- 
Sakari Ailus

Re: [PATCH v3] software_node: Add kernel-doc comments to exported symbols

[Daniel Scally]

Hi Sakari

On 20/01/2021 10:35, Sakari Ailus wrote:
> Hi Dan,
>
> On Wed, Jan 20, 2021 at 12:03:39AM +0000, Daniel Scally wrote:
>> A number of functions which are exported via EXPORT_SYMBOL_GPL() lack any
>> kernel-doc comments; add those in so all exported symbols are documented.
>>
>> Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
>> Reviewed-by: Heikki Krogerus <heikki.krogerus@linux.intel.com>
>> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
>> Reviewed-by: Sakari Ailus <sakari.ailus@linux.intel.com>
>> Signed-off-by: Daniel Scally <djrscally@gmail.com>
>> ---
>> Changelog for v3:
>>
>> 	- s/passed to @parent/passed as @parent
>> 	- Wrapped a long summary line - TIL that you can do that, thanks
>> 	  Sakari
>>
>>  drivers/base/swnode.c | 54 +++++++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 54 insertions(+)
>>
>> diff --git a/drivers/base/swnode.c b/drivers/base/swnode.c
>> index 4a4b2008fbc2..39fbb653c58a 100644
>> --- a/drivers/base/swnode.c
>> +++ b/drivers/base/swnode.c
>> @@ -33,6 +33,13 @@ static struct kset *swnode_kset;
>>  
>>  static const struct fwnode_operations software_node_ops;
>>  
>> +/**
>> + * is_software_node() - check if given fwnode was created from a software_node
>> + * @fwnode: The &struct fwnode_handle to check
>> + *
>> + * This function is used to check whether a given firmware node handle was
>> + * created by registering a &struct software_node or not.
>> + */
>>  bool is_software_node(const struct fwnode_handle *fwnode)
>>  {
>>  	return !IS_ERR_OR_NULL(fwnode) && fwnode->ops == &software_node_ops;
>> @@ -71,6 +78,15 @@ software_node_to_swnode(const struct software_node *node)
>>  	return swnode;
>>  }
>>  
>> +/**
>> + * to_software_node() - Fetch the software node used to create a firmware
>> + *			node handle
>> + * @fwnode: The pointer to a &struct fwnode_handle to parse
>> + *
>> + * This function attempts to fetch a pointer to the &struct software_node which
>> + * was used to create the given @fwnode. Note that this will only work if the
>> + * software node has **not** been released.
>> + */
>>  const struct software_node *to_software_node(const struct fwnode_handle *fwnode)
>>  {
>>  	const struct swnode *swnode = to_swnode(fwnode);
>> @@ -79,6 +95,14 @@ const struct software_node *to_software_node(const struct fwnode_handle *fwnode)
>>  }
>>  EXPORT_SYMBOL_GPL(to_software_node);
>>  
>> +/**
>> + * software_node_fwnode() - Fetch firmware node associated with a given software node
>> + * @node: The pointer to a &struct software_node to parse
>> + *
>> + * This function attempts to fetch a pointer to the &struct fwnode_handle which
>> + * was created from the given @node. Note that this will only work after the
>> + * software node has been registered.
>> + */
>>  struct fwnode_handle *software_node_fwnode(const struct software_node *node)
>>  {
>>  	struct swnode *swnode = software_node_to_swnode(node);
>> @@ -800,6 +824,27 @@ void software_node_unregister(const struct software_node *node)
>>  }
>>  EXPORT_SYMBOL_GPL(software_node_unregister);
>>  
>> +/**
>> + * fwnode_create_software_node() - Create and register a new software_node
>> + * @properties: NULL terminated array of properties to assign to the new node
>> + * @parent: Pointer to a &struct fwnode_handle to assign as parent to the new
>> + *	    node
>> + *
>> + * NOTE: The pointer passed as @parent **must** be to a firmware node handle
>> + * that was created by registering a software node, meaning is_software_node()
>> + * must return true when passed that pointer.
>> + *
>> + * This function creates a new instance of &struct software_node, assigns it a
>> + * copy of the given array of properties and registers it as a new fwnode_handle.
>> + * Freeing of the allocated memory when the fwnode_handle is no longer needed is
>> + * handled via software_node_release() and does not need to be done separately.
> Please wrap all lines over 80 unless there's a reason to keep them longer.


Apologies; I'll cat | awk for lines over the limit from now on rather
than half-arsing it.

>
>> + *
>> + * Returns:
>> + * * fwnode_handle *	- On success
>> + * * -EINVAL		- When @parent is not associated with a software_node
>> + * * -ENOMEM		- When memory allocation fails
>> + * * -Other		- Propagated errors from sub-functions
>> + */
>>  struct fwnode_handle *
>>  fwnode_create_software_node(const struct property_entry *properties,
>>  			    const struct fwnode_handle *parent)
>> @@ -832,6 +877,15 @@ fwnode_create_software_node(const struct property_entry *properties,
>>  }
>>  EXPORT_SYMBOL_GPL(fwnode_create_software_node);
>>  
>> +/**
>> + * fwnode_remove_software_node() - Put a reference to a registered software_node
>> + * @fwnode: The pointer to the &struct fwnode_handle you want to release
>> + *
>> + * Release a reference to a registered &struct software_node. This function
>> + * differs from software_node_put() in that it takes no action if the
>> + * firmware node handle passed to @fwnode turns out not to have been created by
>> + * registering a software_node.
>> + */
>>  void fwnode_remove_software_node(struct fwnode_handle *fwnode)
>>  {
>>  	struct swnode *swnode = to_swnode(fwnode);
>> -- 
>> 2.25.1
>>

Re: [PATCH v3] software_node: Add kernel-doc comments to exported symbols

[Andy Shevchenko]

On Wed, Jan 20, 2021 at 11:11:47AM +0000, Daniel Scally wrote:
> On 20/01/2021 10:35, Sakari Ailus wrote:
> > On Wed, Jan 20, 2021 at 12:03:39AM +0000, Daniel Scally wrote:

> >> +/**
> >> + * fwnode_create_software_node() - Create and register a new software_node
> >> + * @properties: NULL terminated array of properties to assign to the new node
> >> + * @parent: Pointer to a &struct fwnode_handle to assign as parent to the new
> >> + *	    node
> >> + *
> >> + * NOTE: The pointer passed as @parent **must** be to a firmware node handle
> >> + * that was created by registering a software node, meaning is_software_node()
> >> + * must return true when passed that pointer.
> >> + *
> >> + * This function creates a new instance of &struct software_node, assigns it a
> >> + * copy of the given array of properties and registers it as a new fwnode_handle.
> >> + * Freeing of the allocated memory when the fwnode_handle is no longer needed is
> >> + * handled via software_node_release() and does not need to be done separately.
> > Please wrap all lines over 80 unless there's a reason to keep them longer.

> Apologies; I'll cat | awk for lines over the limit from now on rather
> than half-arsing it.

In Vim, for example, you may set the threshold and it will wrap it for you.
Also, taking into account famous *useless use of cat*, you may use `fold` or `fmt`

> >> + *
> >> + * Returns:
> >> + * * fwnode_handle *	- On success
> >> + * * -EINVAL		- When @parent is not associated with a software_node
> >> + * * -ENOMEM		- When memory allocation fails
> >> + * * -Other		- Propagated errors from sub-functions
> >> + */

-- 
With Best Regards,
Andy Shevchenko