[PATCH 00/11] PM: runtime: Overhaul kerneldoc, runtime_pm.rst docs

[Brian Norris]

This series started as a relatively small observation last year, that
Documentation/power/runtime_pm.rst includes a number of API descriptions
that duplicate similar docs in the source/header files, and that they
tend to be a bit more out of date. This is a great case for pulling
kerneldoc into the generated documents, so the docs can live closer to
the code.

Per Rafael, "that's the plan for the future":
https://lore.kernel.org/all/CAJZ5v0jFdUDN_Z5isEpWoisxzMHSgzu460VH2LDCLQTRsUtEDA@xxxxxxxxxxxxxx/

The future is now!

Of course, nothing is ever that trivial. I found several other itches to
scratch along the way:

 * Basic warning-free kerneldoc validation (resolved in patch 1)

 * Touch-ups to the existing kerneldoc (misleading descriptions,
   borrowing valuable work from the soon-to-be-deleted runtime_pm.rst
   portions, trying to improve ease of reading/understanding) in patch 2
   and 3

 * Pull drivers/base/power/runtime.c and include/linux/pm_runtime.h
   kerneldoc into generated runtime_pm html (patch 4)

 * Move dev_pm_info descriptions (+ more) from runtime_pm.rst into
   include/linux/pm.h kerneldoc (patch 5)

 * Overall reworks, fixes, and (IMO) improvements to runtime_pm.rst, for
   clarity, and hopefully to make an easier and more useful read to
   driver writers and people less familiar with the subsystem (patches
   6-11).

   Highlights (IMO):

   - Clarifying core concepts in the Introduction. (Pretty much all new
     readers I encounter have a hard time with the difference between
     "enabled", "allowed", and "active".)

   - Adding Example driver patterns -- because the API is so large and
     complicated, it can help to try to walk people through standard
     practices, and what everything means in context.

I purposely kept some of the larger changes toward the end, to hopefully
make it easier to rework or reject them while cherry-picking some of the
easier stuff from the first part of the series.

Feel free to add suggestions! Within reason, I'm open to tackling more
here, as I think many people have many valid perspectives on exactly why
and how the docs do or don't serve people well today. Or I can tackle
less, if you think some of my choices are not improvements.

Some possible follow-ups I'm toying with:

 * Slimming down the API might be better than heavily documenting it. A
   smaller API is a more digestible API.

   My only concrete next step: drop __pm_runtime_put_autosuspend(). Its
   last user is nearly gone:
   https://lore.kernel.org/all/20260806-smmu-rpm-v4-1-8183d007331c@xxxxxxxxxxxxxxxx/

   I could also see deprecating one of
   pm_runtime_put_sync{,_suspend,_autosuspend}(). They all do slightly
   different things, but I'm not sure every difference is actually fully
   intentional (or at least, not necessary).

 * Tweaking some of the behavior on pm_runtime_barrier(). Today, it's
   very asymmetric, as it prefers resume. But I believe there may be
   value in making it flush (not just cancel) pending suspend too. That
   may be in a future proposal; for now, I just try to make its
   asymmetry more clear in the docs.

 * Sand down some more rough edges on return codes. For example, it's
   very difficult to get any useful meaning out of pm_runtime_put_sync()
   return codes. There's a high chance that anyone trying to treat
   return codes as errors is inviting bugs. (Is -EAGAIN a failure?)

   Of course, the answer there is not "document it better" -- we can
   make it easier to use.

Regards,
Brian


Brian Norris (11):
  PM: runtime: kerneldoc fixes
  PM: runtime: Improve set_{status,active,suspended} docs
  PM: runtime: kerneldoc wording improvements
  PM: runtime: Pull API docs from kerneldoc
  PM: core: Document struct dev_pm_info with kerneldoc
  PM: runtime: Expand introduction with core concepts and structure
  PM: runtime: Clarify ->runtime_idle() callback return value handling
  PM: runtime: Clarify driver callback expectations and structure
    Section 2
  PM: runtime: Misc improvements to runtime_pm.rst
  PM: runtime: Add "Section" hyperlinks
  PM: runtime: Add Example Driver Patterns section

 Documentation/power/runtime_pm.rst | 915 ++++++++++++++++-------------
 drivers/base/power/runtime.c       |  93 +--
 include/linux/pm.h                 |  93 +++
 include/linux/pm_runtime.h         | 409 +++++++------
 4 files changed, 878 insertions(+), 632 deletions(-)

-- 
2.55.0.979.g7e5102b832-goog