linux-kernel - Re: [PATCH v3 4/5] iio: light: ROHM BU27008 color sensor

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <ZFjt33rdupWOAsc8@smile.fi.intel.com>
Date:   Mon, 8 May 2023 15:41:03 +0300
From:   Andy Shevchenko <andriy.shevchenko@...ux.intel.com>
To:     Jonathan Cameron <jic23@...nel.org>
Cc:     "Vaittinen, Matti" <Matti.Vaittinen@...rohmeurope.com>,
        Matti Vaittinen <mazziesaccount@...il.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 Sun, May 07, 2023 at 03:24:43PM +0100, Jonathan Cameron wrote:
> On Wed, 3 May 2023 05:11:53 +0000
> "Vaittinen, Matti" <Matti.Vaittinen@...rohmeurope.com> wrote:
> > On 5/2/23 23:40, Andy Shevchenko wrote:
> > > On Wed, Apr 26, 2023 at 11:08:17AM +0300, Matti Vaittinen wrote:  

...

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

I can run it manually and see in a nice form instead of browsing file for that,
so there is still a usefulness in my opinion. Esp. taking into account that
comments are already there. It's just different and helpful form of
representation. No?


-- 
With Best Regards,
Andy Shevchenko