Re: [PATCH v2 1/2] driver core: bus.h: document bus notifiers better

[Greg Kroah-Hartman]

On Tue, Jan 10, 2023 at 09:03:52AM -0800, Randy Dunlap wrote:
> Hi Greg,
> 
> On 1/10/23 06:53, Greg Kroah-Hartman wrote:
> > The bus notifier values are not documented all that well, so clean this
> > up and make a real enumerated type for them and document them much
> > better.  Also change the values from being in hex to just decimal as it
> > didn't make any sense to have them in hex.
> > 
> > Cc: "Rafael J. Wysocki" <rafael@xxxxxxxxxx>
> > Signed-off-by: Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx>
> > ---
> > v2: move the values to decimal from hex as pointed out by Rafael.
> > 
> >  include/linux/device/bus.h | 43 +++++++++++++++++++++++++-------------
> >  1 file changed, 29 insertions(+), 14 deletions(-)
> > 
> > diff --git a/include/linux/device/bus.h b/include/linux/device/bus.h
> > index d529f644e92b..fbec1c7c34c0 100644
> > --- a/include/linux/device/bus.h
> > +++ b/include/linux/device/bus.h
> > @@ -257,21 +257,36 @@ extern int bus_register_notifier(struct bus_type *bus,
> >  extern int bus_unregister_notifier(struct bus_type *bus,
> >  				   struct notifier_block *nb);
> >  
> > -/* All 4 notifers below get called with the target struct device *
> > - * as an argument. Note that those functions are likely to be called
> > - * with the device lock held in the core, so be careful.
> 
> If you want this to be kernel-doc format with no warnings,
> (a) all of the " * BUS_NOTIFY_..." lines should be " * @BUS_NOTIFY_...";
> (b) all of the " * @BUS_NOTIFY_..." lines should be immediately after the
> second ("enum") line. (at [1])
> (c) In the heading "enum" line, s/: / - /, but that's just for consistency
> and to follow kernel-doc documented format; it seems that kernel-doc takes
> that separator either way.
> 
> The patch below (on top of this one) makes all of these changes.

Ah, thank you so much for that, I'll merge your changes into here, and
also drop the explicit values for the enums as that really does not
matter at all.

thanks,

greg k-h