From: Jonathan Cameron <jic23@kernel.org>
To: Matti Vaittinen <mazziesaccount@gmail.com>
Cc: Jonathan Cameron <Jonathan.Cameron@Huawei.com>,
"Vaittinen, Matti" <Matti.Vaittinen@fi.rohmeurope.com>,
linux-iio <linux-iio@vger.kernel.org>,
Mauro Carvalho Chehab <mchehab@kernel.org>,
linux-doc@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>
Subject: Re: ROHM ALS, integration time
Date: Mon, 30 Jan 2023 20:19:29 +0000 [thread overview]
Message-ID: <20230130201929.52c93ee5@jic23-huawei> (raw)
In-Reply-To: <0e0d45b7-e582-82b2-9bac-1f70f9dad9f7@gmail.com>
On Mon, 30 Jan 2023 20:19:07 +0200
Matti Vaittinen <mazziesaccount@gmail.com> wrote:
> On 1/30/23 19:12, Jonathan Cameron wrote:
> > On Mon, 30 Jan 2023 13:42:27 +0000
> > "Vaittinen, Matti" <Matti.Vaittinen@fi.rohmeurope.com> wrote:
> >
> >> On 1/30/23 15:02, Jonathan Cameron wrote:
> >>> On Mon, 30 Jan 2023 14:04:53 +0200
> >>> Matti Vaittinen <mazziesaccount@gmail.com> wrote:
> >> For an occasional contributor like me it could be helpful if the defines
> >> like IIO_INTENSITY, IIO_LIGHT had documentation in headers explaining
> >> for example the units. Maybe also some words about the
> >> IIO_CHAN_INFO_INT_TIME and IIO_CHAN_INFO_SCALE as well ;) I guess I can
> >> cook some doc - but only for couple of defines which I have discussed
> >> with you this far. Do you think such comment docs would be welcome -
> >> even if they covered only couple of defines? Maybe others would continue
> >> from that.
> >
> > I'd worry about the Docs disagreeing with the ABI docs
> > in Documentation/ABI/testing/sysfs-bus-iio
> > which needs to be the 'one true source' of this stuff.
>
> Oh, right. It might've been just me - but I did overlook this golden
> documentation. I did actually land on this document but didn't really
> pay the required attention. I guess I allowed the kernel version in the
> page to distract me thinking it is some sort of 'history' stuff.
>
> What would have been enough (even for me) would've been a short
> description of a define - and then the link to a entry which corresponds
> the define in this document. Something along the lines:
>
> /**
> * iio_chan_type - Types of channel
> *
> * Please find the detailed documentation for reported values from the
> * Documentation/ABI/testing/sysfs-bus-iio. Pointer to correct keyword
> * in documentation is mentioned at the channel define description
> * below.
> *
> * IIO_INTENSITY: Channel for unitless intensity.
> * Doc keyword: in_intensityY_raw
> *
> * IIO_LIGHT: Channel for visible light intensity in lux
> * Doc keyword: in_illuminance_raw
> */
>
> I have a feeling that this would already have helped me. Nevertheless, I
> would not mind seeing docs also for the iio_chan_info_enum values - but
> linking to the correct spot in sysfs-bus-iio might not be as easy.
>
> Anyays, Thanks for the help once again :)
Both the kernel-doc for this header and the ABI docs end up in
the kernel html docs. I wonder if a link is possible...
https://docs.kernel.org/driver-api/iio/core.html#industrial-i-o-devices
would have the iio_chan_type docs I think if there were any.
https://docs.kernel.org/admin-guide/abi-testing.html?highlight=abi#abi-sys-iio-devicex-in-intensityy-raw
is the matching ABI doc.
Mauro, Jon, other docs system experts...
I couldn't immediately find a way to link to a specific ABI docs entry,
is there a means to do it from kernel-doc in a header?
Thanks,
Jonathan
>
> Yours,
> -- Matti
>
next parent reply other threads:[~2023-01-30 20:05 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <65c7c45a-c953-e418-f640-9e46841151a1@gmail.com>
[not found] ` <20230130130231.000013b6@Huawei.com>
[not found] ` <9b3dcc7a-a0f8-38ee-4381-d330004d436f@fi.rohmeurope.com>
[not found] ` <20230130171218.00007802@Huawei.com>
[not found] ` <0e0d45b7-e582-82b2-9bac-1f70f9dad9f7@gmail.com>
2023-01-30 20:19 ` Jonathan Cameron [this message]
2023-01-31 19:58 ` ROHM ALS, integration time Jonathan Corbet
2023-02-01 5:55 ` Matti Vaittinen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20230130201929.52c93ee5@jic23-huawei \
--to=jic23@kernel.org \
--cc=Jonathan.Cameron@Huawei.com \
--cc=Matti.Vaittinen@fi.rohmeurope.com \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-iio@vger.kernel.org \
--cc=mazziesaccount@gmail.com \
--cc=mchehab@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).