Re: [PATCH v2] software_node: Add kernel-doc comments to exported symbols
On Mon, Jan 18, 2021 at 11:49:46AM +0200, Sakari Ailus wrote: > On Wed, Jan 13, 2021 at 12:02:09AM +, Daniel Scally wrote: > > + * 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. -- With Best Regards, Andy Shevchenko
Re: [PATCH v2] software_node: Add kernel-doc comments to exported symbols
On 18/01/2021 10:33, Andy Shevchenko wrote: > On Mon, Jan 18, 2021 at 11:49:46AM +0200, Sakari Ailus wrote: >> On Wed, Jan 13, 2021 at 12:02:09AM +, Daniel Scally wrote: >>> + * 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
Re: [PATCH v2] software_node: Add kernel-doc comments to exported symbols
On Mon, Jan 18, 2021 at 12:33:55PM +0200, Andy Shevchenko wrote: > On Mon, Jan 18, 2021 at 11:49:46AM +0200, Sakari Ailus wrote: > > On Wed, Jan 13, 2021 at 12:02:09AM +, Daniel Scally wrote: > > > > + * 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. -- Sakari Ailus
Re: [PATCH v2] software_node: Add kernel-doc comments to exported symbols
Hi Daniel,
On Wed, Jan 13, 2021 at 12:02:09AM +, 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
> Reviewed-by: Heikki Krogerus
> Signed-off-by: Daniel Scally
> ---
> 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(+)
>
> diff --git a/drivers/base/swnode.c b/drivers/base/swnode.c
> index 4a4b2008fbc2..e98018aa8b2f 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,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).
Reviewed-by: Sakari Ailus
> + * @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);
> --
> 2.25.1
>
--
Sakari Ailus
Re: [PATCH v2] software_node: Add kernel-doc comments to exported symbols
Hi Randy
On 13/01/2021 01:01, Randy Dunlap wrote:
> On 1/12/21 4:02 PM, 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
>> Reviewed-by: Heikki Krogerus
>> Signed-off-by: Daniel Scally
>> ---
>> 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(+)
>>
>> diff --git a/drivers/base/swnode.c b/drivers/base/swnode.c
>> index 4a4b2008fbc2..e98018aa8b2f 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,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
> maybe: passed as @parent
> ?
Sure, I'll make that change.
> Otherwise, LGTM. Thanks for doing this.
>
> Reviewed-by: Randy Dunlap
Thanks!
>
>> + * 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.
>> + */
>
Re: [PATCH v2] software_node: Add kernel-doc comments to exported symbols
On 1/12/21 4:02 PM, 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
> Reviewed-by: Heikki Krogerus
> Signed-off-by: Daniel Scally
> ---
> 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(+)
>
> diff --git a/drivers/base/swnode.c b/drivers/base/swnode.c
> index 4a4b2008fbc2..e98018aa8b2f 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,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
maybe: passed as @parent
?
Otherwise, LGTM. Thanks for doing this.
Reviewed-by: Randy Dunlap
> + * 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);
>
--
~Randy
You can't do anything without having to do something else first.
-- Belefant's Law
[PATCH v2] 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.
Reviewed-by: Andy Shevchenko
Reviewed-by: Heikki Krogerus
Signed-off-by: Daniel Scally
---
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(+)
diff --git a/drivers/base/swnode.c b/drivers/base/swnode.c
index 4a4b2008fbc2..e98018aa8b2f 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,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);
--
2.25.1
