Re: ROHM ALS, integration time

Re: ROHM ALS, integration time

[Jonathan Cameron]

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
> 

Re: ROHM ALS, integration time

[Jonathan Corbet]

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

Re: ROHM ALS, integration time

[Matti Vaittinen]

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