[PATCH] pwm: Fix various formatting issues in kernel-doc

[PATCH] pwm: Fix various formatting issues in kernel-doc

[Uwe Kleine-König]

Add Return and (where interesting) Context sections, fix some formatting
and drop documenting the internal function __pwm_apply().

Signed-off-by: Uwe Kleine-König <u.kleine-koenig@baylibre.com>
---
Hello Jonathan,

while looking into the warning that Stephen reported in
https://lore.kernel.org/linux-next/20250417162700.728e14e5@canb.auug.org.au,
I found a few more issues fixed here.

I intend to merge this via my pwm tree, but getting a confirmation (or critic)
from someone who knows kernel-doc better than me would be great.

Best regards
Uwe

 drivers/pwm/core.c  | 30 ++++++++++++++++++++++--------
 include/linux/pwm.h |  8 +++++---
 2 files changed, 27 insertions(+), 11 deletions(-)

diff --git a/drivers/pwm/core.c b/drivers/pwm/core.c
index 079964961bd8..447077776bce 100644
--- a/drivers/pwm/core.c
+++ b/drivers/pwm/core.c
@@ -222,8 +222,10 @@ static int __pwm_write_waveform(struct pwm_chip *chip, struct pwm_device *pwm, c
  * Note however that the world doesn't stop turning when you call it, so when
  * doing
  *
- * 	pwm_round_waveform_might_sleep(mypwm, &wf);
- * 	pwm_set_waveform_might_sleep(mypwm, &wf, true);
+ * .. code-block:: C
+ *
+ *   pwm_round_waveform_might_sleep(mypwm, &wf);
+ *   pwm_set_waveform_might_sleep(mypwm, &wf, true);
  *
  * the latter might fail, e.g. because an input clock changed its rate between
  * these two calls and the waveform determined by
@@ -233,8 +235,9 @@ static int __pwm_write_waveform(struct pwm_chip *chip, struct pwm_device *pwm, c
  * value (in the order period_length_ns, duty_length_ns and then
  * duty_offset_ns). Only if this isn't possible, a value might grow.
  *
- * Returns 0 on success, 1 if at least one value had to be rounded up or a
+ * Returns: 0 on success, 1 if at least one value had to be rounded up or a
  * negative errno.
+ * Context: May sleep.
  */
 int pwm_round_waveform_might_sleep(struct pwm_device *pwm, struct pwm_waveform *wf)
 {
@@ -291,6 +294,9 @@ EXPORT_SYMBOL_GPL(pwm_round_waveform_might_sleep);
  *
  * Stores the current configuration of the PWM in @wf. Note this is the
  * equivalent of pwm_get_state_hw() (and not pwm_get_state()) for pwm_waveform.
+ *
+ * Returns: 0 on success or a negative errno
+ * Context: May sleep.
  */
 int pwm_get_waveform_might_sleep(struct pwm_device *pwm, struct pwm_waveform *wf)
 {
@@ -406,6 +412,10 @@ static int __pwm_set_waveform(struct pwm_device *pwm,
  * Note that even with exact = true, some rounding by less than 1 is
  * possible/needed. In the above example requesting .period_length_ns = 94 and
  * exact = true, you get the hardware configured with period = 93.5 ns.
+ *
+ * Returns: 0 on succes, 1 if was rounded up (if !@exact) or no perfect match was
+ * possible (if @exact), or a negative errno
+ * Context: May sleep.
  */
 int pwm_set_waveform_might_sleep(struct pwm_device *pwm,
 				 const struct pwm_waveform *wf, bool exact)
@@ -565,11 +575,6 @@ static bool pwm_state_valid(const struct pwm_state *state)
 	return true;
 }
 
-/**
- * __pwm_apply() - atomically apply a new state to a PWM device
- * @pwm: PWM device
- * @state: new state to apply
- */
 static int __pwm_apply(struct pwm_device *pwm, const struct pwm_state *state)
 {
 	struct pwm_chip *chip;
@@ -678,6 +683,9 @@ static int __pwm_apply(struct pwm_device *pwm, const struct pwm_state *state)
  * Cannot be used in atomic context.
  * @pwm: PWM device
  * @state: new state to apply
+ *
+ * Returns: 0 on success, or a negative errno
+ * Context: May sleep.
  */
 int pwm_apply_might_sleep(struct pwm_device *pwm, const struct pwm_state *state)
 {
@@ -719,6 +727,9 @@ EXPORT_SYMBOL_GPL(pwm_apply_might_sleep);
  * Not all PWM devices support this function, check with pwm_might_sleep().
  * @pwm: PWM device
  * @state: new state to apply
+ *
+ * Returns: 0 on success, or a negative errno
+ * Context: Any
  */
 int pwm_apply_atomic(struct pwm_device *pwm, const struct pwm_state *state)
 {
@@ -792,6 +803,9 @@ EXPORT_SYMBOL_GPL(pwm_get_state_hw);
  * This function will adjust the PWM config to the PWM arguments provided
  * by the DT or PWM lookup table. This is particularly useful to adapt
  * the bootloader config to the Linux one.
+ *
+ * Returns: 0 on success or a negative error code on failure.
+ * Context: May sleep.
  */
 int pwm_adjust_config(struct pwm_device *pwm)
 {
diff --git a/include/linux/pwm.h b/include/linux/pwm.h
index bf0469b2201d..63a17d2b4ec8 100644
--- a/include/linux/pwm.h
+++ b/include/linux/pwm.h
@@ -218,6 +218,8 @@ static inline void pwm_init_state(const struct pwm_device *pwm,
  *
  * pwm_get_state(pwm, &state);
  * duty = pwm_get_relative_duty_cycle(&state, 100);
+ *
+ * Returns: rounded relative duty cycle multiplied by @scale
  */
 static inline unsigned int
 pwm_get_relative_duty_cycle(const struct pwm_state *state, unsigned int scale)
@@ -244,8 +246,8 @@ pwm_get_relative_duty_cycle(const struct pwm_state *state, unsigned int scale)
  * pwm_set_relative_duty_cycle(&state, 50, 100);
  * pwm_apply_might_sleep(pwm, &state);
  *
- * This functions returns -EINVAL if @duty_cycle and/or @scale are
- * inconsistent (@scale == 0 or @duty_cycle > @scale).
+ * Returns: 0 on success or ``-EINVAL`` if @duty_cycle and/or @scale are
+ * inconsistent (@scale == 0 or @duty_cycle > @scale)
  */
 static inline int
 pwm_set_relative_duty_cycle(struct pwm_state *state, unsigned int duty_cycle,
@@ -351,7 +353,7 @@ struct pwm_chip {
  * pwmchip_supports_waveform() - checks if the given chip supports waveform callbacks
  * @chip: The pwm_chip to test
  *
- * Returns true iff the pwm chip support the waveform functions like
+ * Returns: true iff the pwm chip support the waveform functions like
  * pwm_set_waveform_might_sleep() and pwm_round_waveform_might_sleep()
  */
 static inline bool pwmchip_supports_waveform(struct pwm_chip *chip)

base-commit: fbf1880bada00ad44bffcc8b4f5fed95b47891dd
-- 
2.47.2

Re: [PATCH] pwm: Fix various formatting issues in kernel-doc

[Jonathan Corbet]

Uwe Kleine-König <u.kleine-koenig@baylibre.com> writes:

> Add Return and (where interesting) Context sections, fix some formatting
> and drop documenting the internal function __pwm_apply().
>
> Signed-off-by: Uwe Kleine-König <u.kleine-koenig@baylibre.com>
> ---
> Hello Jonathan,
>
> while looking into the warning that Stephen reported in
> https://lore.kernel.org/linux-next/20250417162700.728e14e5@canb.auug.org.au,
> I found a few more issues fixed here.
>
> I intend to merge this via my pwm tree, but getting a confirmation (or critic)
> from someone who knows kernel-doc better than me would be great.

Seems generally fine, but ...

> Best regards
> Uwe
>
>  drivers/pwm/core.c  | 30 ++++++++++++++++++++++--------
>  include/linux/pwm.h |  8 +++++---
>  2 files changed, 27 insertions(+), 11 deletions(-)
>
> diff --git a/drivers/pwm/core.c b/drivers/pwm/core.c
> index 079964961bd8..447077776bce 100644
> --- a/drivers/pwm/core.c
> +++ b/drivers/pwm/core.c
> @@ -222,8 +222,10 @@ static int __pwm_write_waveform(struct pwm_chip *chip, struct pwm_device *pwm, c
>   * Note however that the world doesn't stop turning when you call it, so when
>   * doing
>   *
> - * 	pwm_round_waveform_might_sleep(mypwm, &wf);
> - * 	pwm_set_waveform_might_sleep(mypwm, &wf, true);
> + * .. code-block:: C
> + *
> + *   pwm_round_waveform_might_sleep(mypwm, &wf);
> + *   pwm_set_waveform_might_sleep(mypwm, &wf, true);

Here I would just use an ordinary literal block rather than embedding
Sphinx directives into the comment like that:

 * Note however that the world doesn't stop turning when you call it, so when
 * doing::
 *
 * 	pwm_round_waveform_might_sleep(mypwm, &wf);
 * 	pwm_set_waveform_might_sleep(mypwm, &wf, true);

Thanks,

jon