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@xxxxxxxxxxxx> --- Hello Jonathan, while looking into the warning that Stephen reported in https://lore.kernel.org/linux-next/20250417162700.728e14e5@xxxxxxxxxxxxxxxx, 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
