Message-ID: <20240829085131.1361701-1-wenst@chromium.org>
Date: Thu, 29 Aug 2024 16:51:20 +0800
From: Chen-Yu Tsai <wenst@...omium.org>
To: Mark Brown <broonie@...nel.org>,
	Liam Girdwood <lgirdwood@...il.com>
Cc: Chen-Yu Tsai <wenst@...omium.org>,
	linux-kernel@...r.kernel.org,
	linux-arm-kernel@...ts.infradead.org,
	Andy Shevchenko <andriy.shevchenko@...ux.intel.com>
Subject: [PATCH v2 00/10] regulator: kerneldoc section fixes

Hi,

This is v2 of my regulator kerneldoc fixes series. The series sort of
came as a request from Andy to not move code that already had warnings
without fixing said warnings. So here I'm fixing them first.

Changes since v1:
- Replaced "true, false" with "valid return values" in commit message of
  "Fix regulator_is_supported_voltage() kerneldoc return value".
- Added articles ("the", "a") to the description based on surrounding
  and function implementation context.
  - The indefinite article ("a", "an") is used when the return value can
    vary in the case of negative error numbers or when the returned
    pointer points to a newly allocated memory object.
  - The definite article ("the") is used when a specific return value is
    mentioned, or when the returned pointer points to some existing object.
- Capitalized first word of first sentence in "Return" section.
- Indented "Return" section for regulator_is_enabled().
- s/alloc/allocation/
- s/error code/error number/
- For patch 'regulator: irq_helpers: Add missing "Return" kerneldoc section':
  - Changed subject to "Fix regulator_irq_map_event_simple() kerneldoc".
  - Described output fields in @rid clearly.
- Added patch to fix of_regulator_bulk_get_all() kerneldoc.
- Added patch to align "negative error number" terminology.

Link to v1:
https://lore.kernel.org/all/20240827095550.675018-1-wenst@chromium.org/

The bulk of the fixes are in the regulator core and OF code, but I also
fixed up a few bits in common code that were missing "Return" sections.
There's also a final patch to align terminology around "negative error
number" within the regulator subsystem. These are purely kerneldoc and
comment fixes and don't touch any actual code. I left the devres code
and helpers alone for now.

The patch series is based on next-20240829. Please merge if possible.
I will rebase my I2C OF component prober series [1] on top of them.

Thanks
ChenYu

[1] https://lore.kernel.org/all/20240822092006.3134096-1-wenst@chromium.org/

Chen-Yu Tsai (10):
  regulator: core: Fix short description for
    _regulator_check_status_enabled()
  regulator: core: Fix regulator_is_supported_voltage() kerneldoc return
    value
  regulator: core: Fix incorrectly formatted kerneldoc "Return" sections
  regulator: core: Add missing kerneldoc "Return" sections
  regulator: of: Fix incorrectly formatted kerneldoc "Return" sections
  regulator: fixed: Fix incorrectly formatted kerneldoc "Return" section
  regulator: fixed-helper: Add missing "Return" kerneldoc section
  regulator: irq_helpers: Fix regulator_irq_map_event_simple() kerneldoc
  regulator: of: Fix kerneldoc format for of_regulator_bulk_get_all()
  regulator: Unify "negative error number" terminology in comments

 drivers/regulator/core.c                | 178 +++++++++++++++++-------
 drivers/regulator/devres.c              |  18 +--
 drivers/regulator/fixed-helper.c        |   2 +
 drivers/regulator/fixed.c               |   8 +-
 drivers/regulator/irq_helpers.c         |  17 ++-
 drivers/regulator/max77802-regulator.c  |   4 +-
 drivers/regulator/of_regulator.c        |  21 +--
 drivers/regulator/qcom-rpmh-regulator.c |   6 +-
 drivers/regulator/qcom_smd-regulator.c  |   2 +-
 9 files changed, 170 insertions(+), 86 deletions(-)

-- 
2.46.0.295.g3b9ea8a38a-goog

Powered by blists - more mailing lists