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

[Matti Vaittinen]

On 5/8/23 15:41, Andy Shevchenko wrote:
> 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@xxxxxxxxxxxxxxxxx> 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?

My main objection was a _misunderstanding_ that the kernel-doc formatted 
comments would automatically end up in generated docs. As I wrote, I 
rarely (never) generate the docs. I use the docs from sources, hence it 
is not easy for me to see this value. Nevertheless, I also wrote

>>> and kernel-doc format is not any worse for me to read.

Hence, I did format these comments as kernel-doc in v5. The only slight 
disadvantage (from my perspective) in using the kernel-doc is increased 
amount of lines with pretty much no additional information. I can live 
with that though.

Yours,
	-- Matti

--
Matti Vaittinen
Linux kernel developer at ROHM Semiconductors
Oulu Finland

~~ When things go utterly wrong vim users can always type :help! ~~