| Message ID | 20240829085131.1361701-3-wenst@chromium.org (mailing list archive) |
|---|---|
| State | Accepted, archived |
| Headers | show |
| Series | regulator: kerneldoc section fixes | expand |
On Thu, Aug 29, 2024 at 04:51:22PM +0800, Chen-Yu Tsai wrote: > The kerneldoc for regulator_is_supported_voltage() states that the > return value is a boolean. That is not correct, as it could return an > error number if the check failed. > > Fix the description by expanding it to cover the valid return values and > error conditions. The description is also converted to a proper "Return" > section. ... > - * Returns a boolean. > + * Return: 1 if the voltage range is supported, 0 if not, or a negative error > + * number if @regulator's voltage can't be changed and voltage readback > + * failed. Not sure why you have TABs in the following lines, but I think you have checked the rendered files (html, man, pdf) and all look good. Alternatively it might be written as * Return: * 1 if the voltage range is supported, 0 if not, or a negative error number * if @regulator's voltage can't be changed and voltage readback failed. which should be the same in the render. (Also similar applies to the other patch(es))
On Thu, Aug 29, 2024 at 9:46 PM Andy Shevchenko <andriy.shevchenko@linux.intel.com> wrote: > > On Thu, Aug 29, 2024 at 04:51:22PM +0800, Chen-Yu Tsai wrote: > > The kerneldoc for regulator_is_supported_voltage() states that the > > return value is a boolean. That is not correct, as it could return an > > error number if the check failed. > > > > Fix the description by expanding it to cover the valid return values and > > error conditions. The description is also converted to a proper "Return" > > section. > > ... > > > - * Returns a boolean. > > + * Return: 1 if the voltage range is supported, 0 if not, or a negative error > > + * number if @regulator's voltage can't be changed and voltage readback > > + * failed. > > Not sure why you have TABs in the following lines, but I think you have checked > the rendered files (html, man, pdf) and all look good. It seems that the kernel-doc tool isn't properly trimming the leading whitespace for RST output. However it is doing it correctly for manpage output. And for html, pdf and all the other outputs that go through Sphinx, the latter reformats stuff and seems to drop the extra whitespace. I looked at the kernel-doc a bit, but wasn't able to immediately spot where the problem was. > Alternatively it might be written as > > * Return: > * 1 if the voltage range is supported, 0 if not, or a negative error number > * if @regulator's voltage can't be changed and voltage readback failed. > > which should be the same in the render. The RST output then has extra empty lines. *shrugs* ChenYu > > (Also similar applies to the other patch(es)) > > -- > With Best Regards, > Andy Shevchenko > >
diff --git a/drivers/regulator/core.c b/drivers/regulator/core.c index 763048d6f1ed..0ce3fe1774fe 100644 --- a/drivers/regulator/core.c +++ b/drivers/regulator/core.c @@ -3456,7 +3456,9 @@ EXPORT_SYMBOL_GPL(regulator_get_linear_step); * @min_uV: Minimum required voltage in uV. * @max_uV: Maximum required voltage in uV. * - * Returns a boolean. + * Return: 1 if the voltage range is supported, 0 if not, or a negative error + * number if @regulator's voltage can't be changed and voltage readback + * failed. */ int regulator_is_supported_voltage(struct regulator *regulator, int min_uV, int max_uV)
The kerneldoc for regulator_is_supported_voltage() states that the return value is a boolean. That is not correct, as it could return an error number if the check failed. Fix the description by expanding it to cover the valid return values and error conditions. The description is also converted to a proper "Return" section. Fixes: c5f3939b8fe0 ("regulator: core: Support fixed voltages in regulator_is_supported_voltage()") Signed-off-by: Chen-Yu Tsai <wenst@chromium.org> --- Changes since v1: - Replaced "true, false" in commit message with "valid return values" - Added articles ("the", "a") to the description based on surrounding and function implementation context --- drivers/regulator/core.c | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)