On Sat, 06 Sep 2025, James Bottomley <James.Bottomley@xxxxxxxxxxxxxxxxxxxxx> wrote: > On Fri, 2025-09-05 at 16:06 +0300, Jani Nikula wrote: >> On Fri, 05 Sep 2025, Mauro Carvalho Chehab >> <mchehab+huawei@xxxxxxxxxx> wrote: >> > Em Fri, 05 Sep 2025 12:02:37 +0300 >> > Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> escreveu: >> > >> > > On Wed, 03 Sep 2025, Randy Dunlap <rdunlap@xxxxxxxxxxxxx> wrote: > [...] >> > > > +++ linux-next-20250819/Documentation/driver-api/pm/devices.rst >> > > > @@ -241,6 +241,14 @@ before reactivating its class I/O queues >> > > > More power-aware drivers might prepare the devices for >> > > > triggering system wakeup >> > > > events. >> > > > >> > > > +System states available for drivers >> > > > +----------------------------------- >> > > > + >> > > > +These system states are available for drivers to help them >> > > > determine how to >> > > > +handle state transitions. >> > > > + >> > > > +.. kernel-doc:: include/linux/kernel.h >> > > > + :doc: General system_states available for drivers >> > > > >> > > > Call Sequence Guarantees >> > > > ------------------------ >> > > > >> > > >> > >> > If the problem is with "extern" before enum, fixing kdoc be >> > fairly trivial. >> >> The non-trivial part is deciding whether you're documenting the enum >> type or the variable. Both are equally valid options. > > If you're building a system that's easy to maintain, it shouldn't be at > all non trivial: you add the documentation where someone adding a new > state would find it. i.e. on the enum. If you document the variable, > no-one adding a new state would likely look at it. I get that in this > case they're one after the other, but think about the precedent for > when they're not. Ah, I meant deciding what the *tool* should do with the documentation when the type and the variable are bundled together like here. BR, Jani. -- Jani Nikula, Intel
