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.shevche...@linux.intel.com> > after addressing few nitpicks Thanks for reviewing >> Signed-off-by: Daniel Scally <djrsca...@gmail.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)
