* Re: ROHM ALS, integration time [not found] ` <0e0d45b7-e582-82b2-9bac-1f70f9dad9f7@gmail.com> @ 2023-01-30 20:19 ` Jonathan Cameron 2023-01-31 19:58 ` Jonathan Corbet 0 siblings, 1 reply; 3+ messages in thread From: Jonathan Cameron @ 2023-01-30 20:19 UTC (permalink / raw) To: Matti Vaittinen Cc: Jonathan Cameron, Vaittinen, Matti, linux-iio, Mauro Carvalho Chehab, linux-doc, Jonathan Corbet 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 > ^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: ROHM ALS, integration time 2023-01-30 20:19 ` ROHM ALS, integration time Jonathan Cameron @ 2023-01-31 19:58 ` Jonathan Corbet 2023-02-01 5:55 ` Matti Vaittinen 0 siblings, 1 reply; 3+ messages in thread From: Jonathan Corbet @ 2023-01-31 19:58 UTC (permalink / raw) To: Jonathan Cameron, Matti Vaittinen Cc: Jonathan Cameron, Vaittinen, Matti, linux-iio, Mauro Carvalho Chehab, linux-doc Jonathan Cameron <jic23@kernel.org> writes: > 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? It should just be possible to write out the type or function name and have the links generated automatically. Have you tried just putting "enum iio_chan_type" into the text? If the automarkup code doesn't pick it up, please let me know. Thanks, jon ^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: ROHM ALS, integration time 2023-01-31 19:58 ` Jonathan Corbet @ 2023-02-01 5:55 ` Matti Vaittinen 0 siblings, 0 replies; 3+ messages in thread From: Matti Vaittinen @ 2023-02-01 5:55 UTC (permalink / raw) To: Jonathan Corbet, Jonathan Cameron Cc: Jonathan Cameron, Vaittinen, Matti, linux-iio, Mauro Carvalho Chehab, linux-doc On 1/31/23 21:58, Jonathan Corbet wrote: > Jonathan Cameron <jic23@kernel.org> writes: > >> 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? > > It should just be possible to write out the type or function name and > have the links generated automatically. Have you tried just putting > "enum iio_chan_type" into the text? If the automarkup code doesn't pick > it up, please let me know. As far as I understand - the problem here is that we would like to have a link from the enum/definition doc to a specific place in the ABI document. The ABI document does not have the enum / define / function "link _target_". (I think adding the enum/function name in the ABI doc would generate link from ABI doc to enum/function doc - which would be helpful - but in this case we would like to have a link to opposite direction. From function/enum doc to specific position in a (sysfs) ABI documentation. Please, bear with me if this was what your suggestion should achieve. I'd just like to ensure we are ton a same page with this.) Yours, --Matti -- Matti Vaittinen Linux kernel developer at ROHM Semiconductors Oulu Finland ~~ When things go utterly wrong vim users can always type :help! ~~ ^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2023-02-01 5:55 UTC | newest] Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- [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 ` ROHM ALS, integration time Jonathan Cameron 2023-01-31 19:58 ` Jonathan Corbet 2023-02-01 5:55 ` Matti Vaittinen
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).