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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <3d92e535-c955-502a-24ac-0655752796fc@gmail.com>
Date:   Tue, 5 Jan 2021 15:39:42 +0000
From:   Daniel Scally <djrscally@...il.com>
To:     Andy Shevchenko <andriy.shevchenko@...ux.intel.com>
Cc:     linux-kernel@...r.kernel.org, rafael@...nel.org,
        gregkh@...uxfoundation.org, sakari.ailus@...ux.intel.com,
        heikki.krogerus@...ux.intel.com
Subject: Re: [PATCH] software_node: Add kernel-doc comments to exported
 symbols

Hi Andy

On 05/01/2021 14:53, Andy Shevchenko wrote:
> On Mon, Jan 04, 2021 at 11:47:36PM +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.
> Thanks, it's helpful!
> Reviewed-by: Andy Shevchenko <andriy.shevchenko@...ux.intel.com>
> after addressing few nitpicks
Thanks for reviewing
>> Signed-off-by: Daniel Scally <djrscally@...il.com>
>> ---
>> With a view to maybe writing some documentation once the fwnode_graph_*()
>> functions are also added.
> FWIW, Heikki used to have a draft patch of swnode documentation, not sure
> what's the current status of it.
Oh cool ok; I'll defer to him then.
>> + * 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 +875,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
>> + * fwnode_handle passed to @fwnode turns out not to have been created by
>> + * registering a software_node
> Period at the end.
>
> I'm a bit confused by amount of fwnode_handle in the comments, can you replace
> them with better approach depending on the case:
> - &struct fwnode_handle
> - a parameter as @fwnode or so
> - a general mention (better to use plain English here, something like firmware
>   node handle or so)
Yeah ok, I was trying to do &struct fwnode_handle on the first reference
(or at least earliest that it would fit) and then fwnode_handle
thereafter, but I think I like the suggestion to drop to plain English
at that point instead, so I'll do that (and ditto for software_node /
software node)