On Fri, Feb 17, 2023 at 01:55:43PM +0200, Andy Shevchenko wrote: > 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? Up to you. > > > 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? It's perhaps not the most pressing issue at the moment. Let's see. -- Sakari Ailus
