Re: [PATCH v9 06/10] math.h: Add macros for rounding to closest value

[Devarsh Thakkar]

Hi Andy,

Thanks for the review.

On 28/05/24 02:02, Andy Shevchenko wrote:
> On Sun, May 26, 2024 at 11:38:56PM +0530, Devarsh Thakkar wrote:
..

>> +/**
>> + * round_closest_up - round closest to be multiple of specified value (which is
>> + *                    power of 2) with preference to rounding up
>> +
> 
> Not that big deal, but missing '*' here. Personally I would not even put
> a blank line between Summary and Field Descriptions.
> 

My bad. Yes I would remove the blank line here. This is picked up as warning
from kernel-doc too.

>> + * @x: the value to round
>> + * @y: multiple to round closest to (must be a power of 2)
>> + *
>> + * Rounds @x to closest multiple of @y (which must be a power of 2).
>> + * The value can be either rounded up or rounded down depending upon rounded
>> + * value's closeness to the specified value. If there are two closest possible
>> + * values, i.e. the difference between the specified value and it's rounded up
>> + * and rounded down values is same then preference is given to rounded up
>> + * value.
>> + *
>> + * To perform arbitrary rounding to closest value (not multiple of 2), use
>> + * roundclosest().
>> + *
>> + * Examples :
> 
> What is this suppose to be rendered to?
> 

The file math.h is not rendered as part of kernel-doc right now. I can put
this under Documentation/core-api/kernel-api.rst perhaps I can create a new
section as below:

Rounding, absolute diff and 32bit division macros
-------------------------------------------------

under the section:
CRC and Math Functions in Linux

===============================

is that okay ?

>> + * round_closest_up(17, 4) = 16
>> + * round_closest_up(15, 4) = 16
>> + * round_closest_up(14, 4) = 16
> 
> Btw, is kernel-doc validator happy about all kernel docs you added?
> 

Yes, except the aforementioned blank line.

Regards
Devarsh