[PATCH 0/5] docs: iio: misc fixes and improvements

[PATCH 0/5] docs: iio: misc fixes and improvements

[Luca Ceresoli]

Here are a few minor fixes and improvements to the IIO documentation.

Luca Ceresoli (5):
  docs: iio: fix example formatting
  docs: iio: fix directory naming
  docs: iio: document the 'index' attribute too
  docs: iio: fix bullet list formatting
  docs: iio: mark "repeat" sysfs attribute as optional

 Documentation/driver-api/iio/buffers.rst | 15 ++++++++-------
 Documentation/iio/iio_configfs.rst       |  2 +-
 2 files changed, 9 insertions(+), 8 deletions(-)

-- 
2.30.0

[PATCH 1/5] docs: iio: fix example formatting

[Luca Ceresoli]

This line is part of the code snippet, so it has to be nested in order
to be rendered correctly.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/iio/iio_configfs.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/iio/iio_configfs.rst b/Documentation/iio/iio_configfs.rst
index 3a5d76f9e2b9..dbc61f35ea05 100644
--- a/Documentation/iio/iio_configfs.rst
+++ b/Documentation/iio/iio_configfs.rst
@@ -71,7 +71,7 @@ kernel module following the interface in include/linux/iio/sw_trigger.h::
 	.ops = &iio_trig_sample_ops,
   };
 
-module_iio_sw_trigger_driver(iio_trig_sample);
+  module_iio_sw_trigger_driver(iio_trig_sample);
 
 Each trigger type has its own directory under /config/iio/triggers. Loading
 iio-trig-sample module will create 'trig-sample' trigger type directory
-- 
2.30.0

[PATCH 2/5] docs: iio: fix directory naming

[Luca Ceresoli]

This directory is a, well, directory, not a file.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/driver-api/iio/buffers.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/iio/buffers.rst b/Documentation/driver-api/iio/buffers.rst
index 3ddebddc02ca..9f7dc245d37a 100644
--- a/Documentation/driver-api/iio/buffers.rst
+++ b/Documentation/driver-api/iio/buffers.rst
@@ -28,7 +28,7 @@ IIO buffer setup
 The meta information associated with a channel reading placed in a buffer is
 called a scan element. The important bits configuring scan elements are
 exposed to userspace applications via the
-:file:`/sys/bus/iio/iio:device{X}/scan_elements/*` directory. This file contains
+:file:`/sys/bus/iio/iio:device{X}/scan_elements/` directory. This directory contains
 attributes of the following form:
 
 * :file:`enable`, used for enabling a channel. If and only if its attribute
-- 
2.30.0

[PATCH 3/5] docs: iio: document the 'index' attribute too

[Luca Ceresoli]

Two out of three attributes are documented, document the third one too.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/driver-api/iio/buffers.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/driver-api/iio/buffers.rst b/Documentation/driver-api/iio/buffers.rst
index 9f7dc245d37a..9dad7c94034b 100644
--- a/Documentation/driver-api/iio/buffers.rst
+++ b/Documentation/driver-api/iio/buffers.rst
@@ -34,6 +34,7 @@ attributes of the following form:
 * :file:`enable`, used for enabling a channel. If and only if its attribute
   is non *zero*, then a triggered capture will contain data samples for this
   channel.
+* :file:`index`, the scan_index of the channel.
 * :file:`type`, description of the scan element data storage within the buffer
   and hence the form in which it is read from user space.
   Format is [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] .
-- 
2.30.0

[PATCH 4/5] docs: iio: fix bullet list formatting

[Luca Ceresoli]

This 2nd-level bullet list is not properly ReST-formatted and thus it gets
rendered as a unique paragraph quite unreadable.  Fix by adding spaces as
needed.

While there also swap "shift" and "repeat" so they are in the correct
order.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/driver-api/iio/buffers.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/driver-api/iio/buffers.rst b/Documentation/driver-api/iio/buffers.rst
index 9dad7c94034b..5801caf216a6 100644
--- a/Documentation/driver-api/iio/buffers.rst
+++ b/Documentation/driver-api/iio/buffers.rst
@@ -38,15 +38,16 @@ attributes of the following form:
 * :file:`type`, description of the scan element data storage within the buffer
   and hence the form in which it is read from user space.
   Format is [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] .
+
   * *be* or *le*, specifies big or little endian.
   * *s* or *u*, specifies if signed (2's complement) or unsigned.
   * *bits*, is the number of valid data bits.
   * *storagebits*, is the number of bits (after padding) that it occupies in the
-  buffer.
-  * *shift*, if specified, is the shift that needs to be applied prior to
-  masking out unused bits.
+    buffer.
   * *repeat*, specifies the number of bits/storagebits repetitions. When the
-  repeat element is 0 or 1, then the repeat value is omitted.
+    repeat element is 0 or 1, then the repeat value is omitted.
+  * *shift*, if specified, is the shift that needs to be applied prior to
+    masking out unused bits.
 
 For example, a driver for a 3-axis accelerometer with 12 bit resolution where
 data is stored in two 8-bits registers as follows::
@@ -123,4 +124,3 @@ More details
 .. kernel-doc:: include/linux/iio/buffer.h
 .. kernel-doc:: drivers/iio/industrialio-buffer.c
    :export:
-
-- 
2.30.0

[PATCH 5/5] docs: iio: mark "repeat" sysfs attribute as optional

[Luca Ceresoli]

Show that this field is optional, just like the shift value.

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/driver-api/iio/buffers.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/iio/buffers.rst b/Documentation/driver-api/iio/buffers.rst
index 5801caf216a6..e83026aebe97 100644
--- a/Documentation/driver-api/iio/buffers.rst
+++ b/Documentation/driver-api/iio/buffers.rst
@@ -37,7 +37,7 @@ attributes of the following form:
 * :file:`index`, the scan_index of the channel.
 * :file:`type`, description of the scan element data storage within the buffer
   and hence the form in which it is read from user space.
-  Format is [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] .
+  Format is [be|le]:[s|u]bits/storagebits[Xrepeat][>>shift] .
 
   * *be* or *le*, specifies big or little endian.
   * *s* or *u*, specifies if signed (2's complement) or unsigned.
-- 
2.30.0

Re: [PATCH 4/5] docs: iio: fix bullet list formatting

[Jonathan Cameron]

On Mon, 15 Feb 2021 15:35:10 +0100
Luca Ceresoli <luca@lucaceresoli.net> wrote:

> This 2nd-level bullet list is not properly ReST-formatted and thus it gets
> rendered as a unique paragraph quite unreadable.  Fix by adding spaces as
> needed.
> 
> While there also swap "shift" and "repeat" so they are in the correct
> order.
> 
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> ---
>  Documentation/driver-api/iio/buffers.rst | 10 +++++-----
>  1 file changed, 5 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/driver-api/iio/buffers.rst b/Documentation/driver-api/iio/buffers.rst
> index 9dad7c94034b..5801caf216a6 100644
> --- a/Documentation/driver-api/iio/buffers.rst
> +++ b/Documentation/driver-api/iio/buffers.rst
> @@ -38,15 +38,16 @@ attributes of the following form:
>  * :file:`type`, description of the scan element data storage within the buffer
>    and hence the form in which it is read from user space.
>    Format is [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] .
> +
>    * *be* or *le*, specifies big or little endian.
>    * *s* or *u*, specifies if signed (2's complement) or unsigned.
>    * *bits*, is the number of valid data bits.
>    * *storagebits*, is the number of bits (after padding) that it occupies in the
> -  buffer.
> -  * *shift*, if specified, is the shift that needs to be applied prior to
> -  masking out unused bits.
> +    buffer.
>    * *repeat*, specifies the number of bits/storagebits repetitions. When the
> -  repeat element is 0 or 1, then the repeat value is omitted.
> +    repeat element is 0 or 1, then the repeat value is omitted.
> +  * *shift*, if specified, is the shift that needs to be applied prior to
> +    masking out unused bits.
>  
>  For example, a driver for a 3-axis accelerometer with 12 bit resolution where
>  data is stored in two 8-bits registers as follows::
> @@ -123,4 +124,3 @@ More details
>  .. kernel-doc:: include/linux/iio/buffer.h
>  .. kernel-doc:: drivers/iio/industrialio-buffer.c
>     :export:
> -
This shouldn't be in here really but it's so minor lets not bother fixing it.

Jonathan

Re: [PATCH 0/5] docs: iio: misc fixes and improvements

[Jonathan Cameron]

On Mon, 15 Feb 2021 15:35:06 +0100
Luca Ceresoli <luca@lucaceresoli.net> wrote:

> Here are a few minor fixes and improvements to the IIO documentation.
> 
> Luca Ceresoli (5):
>   docs: iio: fix example formatting
>   docs: iio: fix directory naming
>   docs: iio: document the 'index' attribute too
>   docs: iio: fix bullet list formatting
>   docs: iio: mark "repeat" sysfs attribute as optional
> 
>  Documentation/driver-api/iio/buffers.rst | 15 ++++++++-------
>  Documentation/iio/iio_configfs.rst       |  2 +-
>  2 files changed, 9 insertions(+), 8 deletions(-)
> 
Applied to the togreg branch of iio.git and pushed out as testing
for reasons not particularly related to these patches (though I guess
0-day might do a docs build occasionally)

Jonathan