software_node: Add kernel-doc comments to exported symbols
Subsystems (2)
Daniel Scally
reviewerPATCH 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
@@ -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
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.Reviewed-by Andy Shevchenko <[email protected]>Reviewed-by Heikki Krogerus <[email protected]>Signed-off-by Daniel Scally <[email protected]>---
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@@ -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
Daniel Scally
reviewerHi 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.Reviewed-by Andy Shevchenko <[email protected]>Reviewed-by Heikki Krogerus <[email protected]>Signed-off-by Daniel Scally <[email protected]>---
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@@ -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.
Reviewed-by Randy Dunlap <[email protected]>
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);
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.Reviewed-by Andy Shevchenko <[email protected]>Reviewed-by Heikki Krogerus <[email protected]>Signed-off-by Daniel Scally <[email protected]>---
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@@ -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
Andy Shevchenko
reviewerQuoted 5 lines · Sakari Ailus
Quoted 1 line · Daniel Scally
+ *
to_software_node()- Fetch software node associated with a firmware node handlePlease 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
Sakari Ailus
reviewerQuoted 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 handlePlease 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
Daniel Scally
reviewerQuoted 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 handlePlease 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