Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
IronPort-SDR: wPTAZYM+dwrpEDle/8SEgdSClQuZjItfMNctDuXvsnkI7WZ5663BwnOVXiyPuiJKfXAe5rILKA
 cDZFaIIrNiOA==
IronPort-SDR: YfixWJrWgNYv8tr761IPsUQCwe+V6bkXofZSRYPG1yOiH8/5dqXajnm1QoN2lrPZvJ+HjfJDN4
 6SrV3pu6uZAg==
Date:   Thu, 7 Jan 2021 16:19:32 +0200
From:   Heikki Krogerus <heikki.krogerus@linux.intel.com>
To:     Daniel Scally <djrscally@gmail.com>
Cc:     Andy Shevchenko <andriy.shevchenko@linux.intel.com>,
        linux-kernel@vger.kernel.org, rafael@kernel.org,
        gregkh@linuxfoundation.org, sakari.ailus@linux.intel.com
Subject: Re: [PATCH] software_node: Add kernel-doc comments to exported
 symbols
Message-ID: <20210107141932.GJ940479@kuha.fi.intel.com>
References: <20210104234736.419493-1-djrscally@gmail.com>
 <20210105145329.GO4077@smile.fi.intel.com>
 <3d92e535-c955-502a-24ac-0655752796fc@gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <3d92e535-c955-502a-24ac-0655752796fc@gmail.com>
Precedence: bulk

On Tue, Jan 05, 2021 at 03:39:42PM +0000, Daniel Scally wrote:
> 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@linux.intel.com>
> > after addressing few nitpicks
> Thanks for reviewing
> >> Signed-off-by: Daniel Scally <djrscally@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.

I actually had a similar patch prepared as part of the series adding
the documentation for software nodes, but your comments are better
than mine. So, after you have addressed Andy's comments:

Reviewed-by: Heikki Krogerus <heikki.krogerus@linux.intel.com>

> >> + * 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)

-- 
heikki