Date:   Sat, 18 Mar 2023 17:24:56 +0000
From:   Jonathan Cameron <jic23@kernel.org>
To:     Matti Vaittinen <mazziesaccount@gmail.com>
Cc:     Andy Shevchenko <andriy.shevchenko@linux.intel.com>,
        Matti Vaittinen <matti.vaittinen@fi.rohmeurope.com>,
        Lars-Peter Clausen <lars@metafoo.de>,
        Shreeya Patel <shreeya.patel@collabora.com>,
        Paul Gazzillo <paul@pgazz.com>,
        Dmitry Osipenko <dmitry.osipenko@collabora.com>,
        Zhigang Shi <Zhigang.Shi@liteon.com>,
        linux-kernel@vger.kernel.org, linux-iio@vger.kernel.org
Subject: Re: [PATCH v3 2/6] iio: light: Add gain-time-scale helpers
Message-ID: <20230318172456.4190c9f4@jic23-huawei>
In-Reply-To: <bad05e06-3b37-b435-bfac-962aef36cc97@gmail.com>
References: <cover.1678093787.git.mazziesaccount@gmail.com>
        <a4cb9a34ca027867ac014ffe93ca7e8245ce263f.1678093787.git.mazziesaccount@gmail.com>
        <ZAXiKfRbsXpHhwAJ@smile.fi.intel.com>
        <20230312165100.45de0c9b@jic23-huawei>
        <bad05e06-3b37-b435-bfac-962aef36cc97@gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Precedence: bulk


> >>> +/*  
> >>
> >> If it's deliberately not a kernel doc, why to bother to have it looking as one?
> >> It's really a provocative to some people who will come with a patches to "fix"
> >> this...  
> > 
> > Just make it kernel-doc.
> >   
> 
> Are you sure...? I don't like the idea of polluting generated docs with 
> documentation for this type of tiny internal pieces not usable outside 
> this component anyways...

You can use :internal or :external to pick up only the docs you want
when including this stuff form a .rst file.

https://docs.kernel.org/doc-guide/kernel-doc.html


> 
> >>  
> >>> + * iio_gts_get_gain - Convert scale to total gain
> >>> + *
> >>> + * Internal helper for converting scale to total gain.
> >>> + *
> >>> + * @max:	Maximum linearized scale. As an example, when scale is created
> >>> + *		in magnitude of NANOs and max scale is 64.1 - The linearized
> >>> + *		scale is 64 100 000 000.
> >>> + * @scale:	Linearized scale to compte the gain for.
> >>> + *
> >>> + * Return:	(floored) gain corresponding to the scale. -EINVAL if scale
> >>> + *		is invalid.
> >>> + */  
> >   
> >> ...
> >>