Received-SPF: pass (google.com: domain of linux-kernel+bounces-194146-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) client-ip=147.75.199.223;
Date: Wed, 29 May 2024 16:17:07 +0300
From: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
To: Devarsh Thakkar <devarsht@ti.com>
Cc: mchehab@kernel.org, hverkuil-cisco@xs4all.nl,
	linux-media@vger.kernel.org, linux-kernel@vger.kernel.org,
	benjamin.gaignard@collabora.com, sebastian.fricke@collabora.com,
	akpm@linux-foundation.org, gregkh@linuxfoundation.org,
	adobriyan@gmail.com, jani.nikula@intel.com, p.zabel@pengutronix.de,
	airlied@gmail.com, daniel@ffwll.ch, dri-devel@lists.freedesktop.org,
	laurent.pinchart@ideasonboard.com, praneeth@ti.com, nm@ti.com,
	vigneshr@ti.com, a-bhatia1@ti.com, j-luthra@ti.com, b-brnich@ti.com,
	detheridge@ti.com, p-mantena@ti.com, vijayp@ti.com,
	andrzej.p@collabora.com, nicolas@ndufresne.ca, davidgow@google.com,
	dlatypov@google.com
Subject: Re: [PATCH v9 06/10] math.h: Add macros for rounding to closest value
Message-ID: <Zlcq07G697jGqHAg@smile.fi.intel.com>
References: <20240526175655.1093707-1-devarsht@ti.com>
 <20240526180856.1124470-1-devarsht@ti.com>
 <ZlTt-YWzyRyhmT9n@smile.fi.intel.com>
 <86f9ed66-c58e-0b2d-dd2b-4372ff26a3c3@ti.com>
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <86f9ed66-c58e-0b2d-dd2b-4372ff26a3c3@ti.com>
Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo

On Tue, May 28, 2024 at 04:02:30PM +0530, Devarsh Thakkar wrote:
> 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 ?

This is up to you, but what I meant is that you always can render manually
yourself. And I was asking about the result you got when you tried (and you
did, right?) to render to man, html, and pdf.

> >> + * 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.

-- 
With Best Regards,
Andy Shevchenko