Messages in this thread | | | Date | Mon, 8 May 2023 15:48:34 +0300 | From | Matti Vaittinen <> | Subject | Re: [PATCH v3 4/5] iio: light: ROHM BU27008 color sensor |
| |
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@fi.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?
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! ~~
| |