[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <84a732f4-0890-307d-2b08-d7d545f1fc42@gmail.com>
Date: Sun, 7 May 2023 18:49:09 +0300
From: Matti Vaittinen <mazziesaccount@...il.com>
To: Jonathan Cameron <jic23@...nel.org>,
"Vaittinen, Matti" <Matti.Vaittinen@...rohmeurope.com>
Cc: Andy Shevchenko <andriy.shevchenko@...ux.intel.com>,
Lars-Peter Clausen <lars@...afoo.de>,
Rob Herring <robh+dt@...nel.org>,
Krzysztof Kozlowski <krzysztof.kozlowski+dt@...aro.org>,
Shreeya Patel <shreeya.patel@...labora.com>,
Zhigang Shi <Zhigang.Shi@...eon.com>,
Paul Gazzillo <paul@...zz.com>,
"linux-iio@...r.kernel.org" <linux-iio@...r.kernel.org>,
"devicetree@...r.kernel.org" <devicetree@...r.kernel.org>,
"linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>,
Andi Shyti <andi.shyti@...nel.org>
Subject: Re: [PATCH v3 4/5] iio: light: ROHM BU27008 color sensor
On 5/7/23 17:24, Jonathan Cameron wrote:
> On Wed, 3 May 2023 05:11:53 +0000
> "Vaittinen, Matti" <Matti.Vaittinen@...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.
Ah! This makes sense. Thanks for correcting me!
> 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.
I'll use kernel-doc for this then.
Yours,
-- Matti
--
Matti Vaittinen
Linux kernel developer at ROHM Semiconductors
Oulu Finland
~~ When things go utterly wrong vim users can always type :help! ~~
Powered by blists - more mailing lists