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