Skip to contentSkip to conversation

software_node: Add kernel-doc comments to exported symbols

PATCH Superseded Daniel Scally 4 participants 7 messages Jan 13, 2021 – Jan 18, 2021

Subsystems (2)

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore

Daniel Scally

author reviewer
#0 lore raw

PATCH v2 1/1 software_node: Add kernel-doc comments to exported symbols

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.

---
Changes in version 2:
- Replaced "fwnode_handle" with either @fwnode or natural language reference to a firmware node handle as appropriate.

 drivers/base/swnode.c | 53 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
drivers/base/swnode.c +53 -0
index 4a4b2008fbc2..e98018aa8b2f 100644
@@ -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,14 @@ software_node_to_swnode(const struct software_node *node)
 	return swnode;
 }
 
+/**
+ * to_software_node() - Fetch software node associated with 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 +94,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 +823,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 to @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 +876,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);
Signature · 1 line
2.25.1
Reviewed-by on v2 1/1
#1 lore raw
Quoted 63 lines · 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.

---
Changes in version 2:
- Replaced "fwnode_handle" with either @fwnode or natural language reference to a firmware node handle as appropriate.

 drivers/base/swnode.c | 53 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
drivers/base/swnode.c +23 -0
index 4a4b2008fbc2..e98018aa8b2f 100644
@@ -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,14 @@ software_node_to_swnode(const struct software_node *node)
 	return swnode;
 }
 
+/**
+ * to_software_node() - Fetch software node associated with 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 +94,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);

drivers/base/swnode.c void software_node_unregister(const struct software_node *node) · line 832

Quoted 10 lines
drivers/base/swnode.c +7 -0
@@ -800,6 +823,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 to @parent **must** be to a firmware node handle

maybe: passed as @parent
?

Otherwise, LGTM. Thanks for doing this.

Quoted 34 lines
drivers/base/swnode.c +23 -0
+ * 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 +876,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);
Signature · 3 lines
~Randy
You can't do anything without having to do something else first.
-- Belefant's Law
author reviewer
#2 lore raw

Hi Randy

Quoted 67 lines · Randy Dunlap
Quoted 66 lines · 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.

---
Changes in version 2:
- Replaced "fwnode_handle" with either @fwnode or natural language reference to a firmware node handle as appropriate.

 drivers/base/swnode.c | 53 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
drivers/base/swnode.c +23 -0
index 4a4b2008fbc2..e98018aa8b2f 100644
@@ -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,14 @@ software_node_to_swnode(const struct software_node *node)
 	return swnode;
 }
 
+/**
+ * to_software_node() - Fetch software node associated with 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 +94,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 +823,27 @@ void software_node_unregister(const struct software_node *node)
 }
 EXPORT_SYMBOL_GPL(software_node_unregister);
 
Quoted 9 lines

drivers/base/swnode.c void software_node_unregister(const struct software_node *node) · line 832

Quoted 7 lines
drivers/base/swnode.c +7 -0
+/**
+ * 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 to @parent **must** be to a firmware node handle

maybe: passed as @parent
?

Sure, I'll make that change.

Quoted 3 lines

Otherwise, LGTM. Thanks for doing this.

Thanks!

Quoted 36 lines
Quoted 35 lines
drivers/base/swnode.c +23 -0
+ * 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 +876,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);
reviewer Reviewed-by on v2 1/1
#3 lore raw
In reply to Daniel Scally

Hi Daniel,

Quoted 33 lines · 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.

---
Changes in version 2:
- Replaced "fwnode_handle" with either @fwnode or natural language reference to a firmware node handle as appropriate.

 drivers/base/swnode.c | 53 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
drivers/base/swnode.c +7 -0
index 4a4b2008fbc2..e98018aa8b2f 100644
@@ -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;

drivers/base/swnode.c software_node_to_swnode(const struct software_node *node) · line 82

Quoted 5 lines
drivers/base/swnode.c +2 -0
@@ -71,6 +78,14 @@ software_node_to_swnode(const struct software_node *node)
 	return swnode;
 }
 
+/**
+ * to_software_node() - Fetch software node associated with a firmware node handle

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

Quoted 71 lines
drivers/base/swnode.c +44 -0
+ * @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 +94,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 +823,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 to @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 +876,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);
Signature · 1 line
2.25.1
Signature · 1 line
Sakari Ailus
#4 lore raw
Quoted 5 lines · Sakari Ailus
Quoted 1 line · Daniel Scally

+ * to_software_node() - Fetch software node associated with a firmware node handle

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

Does kernel-doc behave good when you wrap the function summary line? My impression that summary should be one line.

Signature · 2 lines
With Best Regards,
Andy Shevchenko
reviewer
#5 lore raw
Quoted 8 lines · Andy Shevchenko
Quoted 5 lines · Sakari Ailus
Quoted 1 line · Daniel Scally

+ * to_software_node() - Fetch software node associated with a firmware node handle

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

Does kernel-doc behave good when you wrap the function summary line?

It does, it's not uncommon to have it split across over multiple lines.

Signature · 1 line
Sakari Ailus
author reviewer
#6 lore raw
In reply to Andy Shevchenko
Quoted 7 lines · Andy Shevchenko
Quoted 3 lines · Sakari Ailus
Quoted 1 line · Daniel Scally

+ * to_software_node() - Fetch software node associated with a firmware node handle

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

Does kernel-doc behave good when you wrap the function summary line? My impression that summary should be one line.

Same, but I can shorten the line by s/associated with/linked to or something along those lines