Date:   Fri, 17 Feb 2023 13:55:43 +0200
From:   Andy Shevchenko <andriy.shevchenko@linux.intel.com>
To:     Sakari Ailus <sakari.ailus@linux.intel.com>
Cc:     linux-acpi@vger.kernel.org, linux-kernel@vger.kernel.org,
        Daniel Scally <djrscally@gmail.com>,
        Heikki Krogerus <heikki.krogerus@linux.intel.com>,
        Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
        "Rafael J. Wysocki" <rafael@kernel.org>,
        Daniel Kaehn <kaehndan@gmail.com>
Subject: Re: [PATCH v1 1/1] device property: Clarify description on returned
 value in some functions
Message-ID: <Y+9rPzw9orlqYkIx@smile.fi.intel.com>
References: <20230216205708.13453-1-andriy.shevchenko@linux.intel.com>
 <Y+9Wqbb+zzvH2Ozb@kekkonen.localdomain>
 <Y+9ek6I0tCMHcHRQ@smile.fi.intel.com>
 <Y+9ihz8La+JrIa/L@kekkonen.localdomain>
 <Y+9k9wkRgE1JOsr0@smile.fi.intel.com>
 <Y+9omTMIzAxWM2by@kekkonen.localdomain>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <Y+9omTMIzAxWM2by@kekkonen.localdomain>
Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo
Precedence: bulk

On Fri, Feb 17, 2023 at 01:44:25PM +0200, Sakari Ailus wrote:
> On Fri, Feb 17, 2023 at 01:28:55PM +0200, Andy Shevchenko wrote:
> > On Fri, Feb 17, 2023 at 01:18:31PM +0200, Sakari Ailus wrote:
> > > On Fri, Feb 17, 2023 at 01:01:39PM +0200, Andy Shevchenko wrote:
> > > > On Fri, Feb 17, 2023 at 12:27:53PM +0200, Sakari Ailus wrote:
> > > > > On Thu, Feb 16, 2023 at 10:57:08PM +0200, Andy Shevchenko wrote:

...

> > > > > >   * fwnode_get_next_child_node - Return the next child node handle for a node
> > > > > >   * @fwnode: Firmware node to find the next child node for.
> > > > > >   * @child: Handle to one of the node's child nodes or a %NULL handle.
> > > > > > + *
> > > > > > + * Caller is responsible to call fwnode_handle_put() on the returned fwnode
> > > > > > + * pointer.
> > > > > 
> > > > > The loop itself will also put the child node, so this is only relevant
> > > > > outside the loop.
> > > > 
> > > > Yes and this is exactly what people stumbled over. Hence this note.
> > > > This call per se doesn't loop, so I didn't get how your comment can
> > > > be transformed to anything here. Care to elaborate a bit more on
> > > > what I have to add here or reword?
> > > 
> > > Ah, indeed. This is achieved by putting the previous child. Generally this
> > > function is used via the loop helper macro and not called directly, hence
> > > the documentation there matters the most. Those functions appear to be
> > > without any documentation though.
> > 
> > So, what should I do?
> 
> Good question.
> 
> How about this text:
> 
> The caller is responsible for calling fwnode_handle_put() put on the
> returned fwnode. Note that this function also puts a reference to @child
> unconditionally.

Fine. Does it mean I have to change existing wording of the first sentence
everywhere?

> This is actually done by the firmware specific implementation, namely on OF
> and at least should be done on swnode.

Yes, that's. But it's not needed to be added.

> A second patch to document the fwnode iterator macros would be nice.

Not the reported problem. Maybe someone else can do the job?

-- 
With Best Regards,
Andy Shevchenko