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;
Message-ID: <5b32c9dc-f14b-f4dc-d3e2-08bd4f4e6465@gmail.com>
Date:   Mon, 8 May 2023 15:48:34 +0300
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.10.0
Content-Language: en-US, en-GB
To:     Andy Shevchenko <andriy.shevchenko@linux.intel.com>,
        Jonathan Cameron <jic23@kernel.org>
Cc:     "Vaittinen, Matti" <Matti.Vaittinen@fi.rohmeurope.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>
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>
 <20230507152443.754f2fab@jic23-huawei> <ZFjt33rdupWOAsc8@smile.fi.intel.com>
From:   Matti Vaittinen <mazziesaccount@gmail.com>
Subject: Re: [PATCH v3 4/5] iio: light: ROHM BU27008 color sensor
In-Reply-To: <ZFjt33rdupWOAsc8@smile.fi.intel.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Precedence: bulk

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! ~~