Quoting Andy Shevchenko (2024-09-02 04:17:12) > On Sat, Aug 31, 2024 at 09:06:48PM -0700, Stephen Boyd wrote: > > The usage of this match function is hard to understand at a glance. > > Document the arguments and the return value so it is clear how to > > implement the function. > > Thank you for the patch! > > ... > > I believe we still use "device property:" in the subject for this header file changes. > $ git log --oneline --no-merges -- include/linux/property.h > Ok. > > > +/** > > + * devcon_match_fn_t - device connection match function > > + * @fwnode: Remote connection's device node > > + * @con_id: Identifier for the connection > > + * @data: Match function caller specific data > > + * > > + * Implement a callback with this function signature to search a fwnode's > > + * connections for a match with a function like device_connection_find_match(). > > + * This function will be called possibly multiple times, once for each > > + * connection. The match function should inspect the @fwnode to look for a > > + * match. The @con_id and @data provided are the same as the @con_id and @data > > + * arguments passed to the functions that take a devcon_match_fn_t argument. > > > + * Note: This function can be called multiple times. > > As noted in the next patch, this would be nice to elaborate (at least to me > this sounds like declaration of idempotency which is unlikely what is > meant, or am I mistaken?). I based this on something that I've already forgotten! :) It's saying that the function you implement shouldn't have side-effects because it will be called many times. I actually wrote above that it will be called "possibly multiple times, once for each connection". Let me try to remove "multiple times".
