Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Sun, 7 May 2023 15:24:43 +0100
From:   Jonathan Cameron <jic23@kernel.org>
To:     "Vaittinen, Matti" <Matti.Vaittinen@fi.rohmeurope.com>
Cc:     Andy Shevchenko <andriy.shevchenko@linux.intel.com>,
        Matti Vaittinen <mazziesaccount@gmail.com>,
        Lars-Peter Clausen <lars@metafoo.de>,
        Rob Herring <robh+dt@kernel.org>,
        Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>,
        Shreeya Patel <shreeya.patel@collabora.com>,
        Zhigang Shi <Zhigang.Shi@liteon.com>,
        Paul Gazzillo <paul@pgazz.com>,
        "linux-iio@vger.kernel.org" <linux-iio@vger.kernel.org>,
        "devicetree@vger.kernel.org" <devicetree@vger.kernel.org>,
        "linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>,
        Andi Shyti <andi.shyti@kernel.org>
Subject: Re: [PATCH v3 4/5] iio: light: ROHM BU27008 color sensor
Message-ID: <20230507152443.754f2fab@jic23-huawei>
In-Reply-To: <307cc8ce-6178-7a86-2c90-eaf0ac8c122d@fi.rohmeurope.com>
References: <cover.1682495921.git.mazziesaccount@gmail.com>
        <fb35de40a3908988f5f83e25d17119e6944d289b.1682495921.git.mazziesaccount@gmail.com>
        <ZFF1NMaR1RYThcSB@smile.fi.intel.com>
        <307cc8ce-6178-7a86-2c90-eaf0ac8c122d@fi.rohmeurope.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Precedence: bulk

On Wed, 3 May 2023 05:11:53 +0000
"Vaittinen, Matti" <Matti.Vaittinen@fi.rohmeurope.com> wrote:

> Hi Andy
> 
> Thanks for the review.
> 
> On 5/2/23 23:40, Andy Shevchenko wrote:
> > On Wed, Apr 26, 2023 at 11:08:17AM +0300, Matti Vaittinen wrote:  
> >> The ROHM BU27008 is a sensor with 5 photodiodes (red, green, blue, clear
> >> and IR) with four configurable channels. Red and green being always
> >> available and two out of the rest three (blue, clear, IR) can be
> >> selected to be simultaneously measured. Typical application is adjusting
> >> LCD backlight of TVs, mobile phones and tablet PCs.
> >>
> >> Add initial support for the ROHM BU27008 color sensor.
> >>   - raw_read() of RGB and clear channels
> >>   - triggered buffer w/ DRDY interrtupt  
> > 
> > ...
> >   
> >> +enum {
> >> +	BU27008_RED,	/* Always data0 */
> >> +	BU27008_GREEN,	/* Always data1 */
> >> +	BU27008_BLUE,	/* data2, configurable (blue / clear) */
> >> +	BU27008_CLEAR,	/* data2 or data3 */
> >> +	BU27008_IR,	/* data3 */
> >> +	BU27008_NUM_CHANS  
> > 
> > Why not converting comments to a kernel-doc?
> >   
> >> +};
> >> +
> >> +enum {
> >> +	BU27008_DATA0, /* Always RED */
> >> +	BU27008_DATA1, /* Always GREEN */
> >> +	BU27008_DATA2, /* Blue or Clear */
> >> +	BU27008_DATA3, /* IR or Clear */
> >> +	BU27008_NUM_HW_CHANS
> >> +};  
> > 
> > Ditto.  
> 
> I see no value having entities which are not intended to be used outside 
> this file documented in any "global" documentation. One who is ever 
> going to use these or wonder what these are - will most likely be 
> watching this file. My personal view is that the generated docs should 
> be kept lean. In my opinion the problem of the day is the time we spend 
> looking for a needle hidden in a haystack. In my opinion adding this to 
> kernel-doc just adds hay :)

> 
> I still can do this if no-one else objects. I almost never look at the 
> generated docs myself. Usually I just look the docs from code files - 
> and kernel-doc format is not any worse for me to read. Still, I can 
> imagine including this type of stuff to generic doc just bloats them and 
> my not serve well those who use them.


Unless someone specifically adds this doc to the main docs build, the
kernel-doc won't end up in the docs anyway. It just provides a nice
bit of consistent formatting. Even if they do add this for some reason,
there are controls on internal vs external (exported stuff) being added
to the docs.

> 
> > 
> > ...
> >   
> >> +	if (int_time < 0)
> >> +		int_time = 400000;  
> > 
> > Adding 3 0:s to drop them below with a heavy division operation? Well done!
> > Or did I miss anything?  
> 
> No. You did not miss anything. This can be improved.
> 
> >   
> >> +	msleep(int_time / 1000);  
> > 
> > USEC_PER_MSEC ?  
> 
> Ok.
> 
> > ...
> >   
> >> +	ret = devm_iio_device_register(dev, idev);
> >> +	if (ret)
> >> +		return dev_err_probe(dev, ret,
> >> +				     "Unable to register iio device\n");
> >> +
> >> +	return ret;  
> > 
> > return 0 will suffice.  
> 
> Ok.
> 
> Thanks,
> 	-- Matti
>