[PATCH 0/5] gpio: uapi: documentation improvements

[PATCH 0/5] gpio: uapi: documentation improvements

[Kent Gibson]

I'm intending to add some GPIO chardev documentation to
Documentation/admin-guide/gpio/chardev.rst (or perhaps
Documentation/userspace-api/??), but that is taking longer than I'd like,
so in the meantime here is a collection of minor documentation tidy-ups
and improvements to the kernel-doc that I've made along the way.
Hopefully nothing controversial - mainly formatting improvements,
and a couple of minor wording changes.

Cheers,
Kent.

Kent Gibson (5):
  gpio: uapi: fix kernel-doc warnings
  gpio: uapi: comment consistency
  gpio: uapi: kernel-doc formatting improvements
  gpio: uapi: remove whitespace
  gpio: uapi: clarify the meaning of 'empty' char arrays

 include/uapi/linux/gpio.h | 106 +++++++++++++++++++-------------------
 1 file changed, 54 insertions(+), 52 deletions(-)


base-commit: 237d96164f2c2b33d0d5094192eb743e9e1b04ad
-- 
2.28.0

[PATCH 1/5] gpio: uapi: fix kernel-doc warnings

[Kent Gibson]

Fix kernel-doc warnings, specifically gpioline_info_changed.padding is
not documented and 'GPIO event types' describes defines, which are not
documented by kernel-doc.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
---
 include/uapi/linux/gpio.h | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/include/uapi/linux/gpio.h b/include/uapi/linux/gpio.h
index 07865c601099..b0d5e7a1c693 100644
--- a/include/uapi/linux/gpio.h
+++ b/include/uapi/linux/gpio.h
@@ -346,6 +346,7 @@ enum {
  * @timestamp: estimate of time of status change occurrence, in nanoseconds
  * @event_type: one of GPIOLINE_CHANGED_REQUESTED, GPIOLINE_CHANGED_RELEASED
  * and GPIOLINE_CHANGED_CONFIG
+ * @padding: reserved for future use
  *
  * Note: struct gpioline_info embedded here has 32-bit alignment on its own,
  * but it works fine with 64-bit alignment too. With its 72 byte size, we can
@@ -469,7 +470,7 @@ struct gpioevent_request {
 	int fd;
 };
 
-/**
+/*
  * GPIO event types
  */
 #define GPIOEVENT_EVENT_RISING_EDGE 0x01
-- 
2.28.0

[PATCH 2/5] gpio: uapi: comment consistency

[Kent Gibson]

Make debounce_period_us field documentation consistent with other fields
in the union.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
---
 include/uapi/linux/gpio.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/uapi/linux/gpio.h b/include/uapi/linux/gpio.h
index b0d5e7a1c693..1fdb0e851f83 100644
--- a/include/uapi/linux/gpio.h
+++ b/include/uapi/linux/gpio.h
@@ -98,7 +98,7 @@ struct gpio_v2_line_values {
  * identifying which field of the attribute union is in use.
  * @GPIO_V2_LINE_ATTR_ID_FLAGS: flags field is in use
  * @GPIO_V2_LINE_ATTR_ID_OUTPUT_VALUES: values field is in use
- * @GPIO_V2_LINE_ATTR_ID_DEBOUNCE: debounce_period_us is in use
+ * @GPIO_V2_LINE_ATTR_ID_DEBOUNCE: debounce_period_us field is in use
  */
 enum gpio_v2_line_attr_id {
 	GPIO_V2_LINE_ATTR_ID_FLAGS		= 1,
-- 
2.28.0

[PATCH 3/5] gpio: uapi: kernel-doc formatting improvements

[Kent Gibson]

Add kernel-doc formatting to all references to structs, enums, fields
and constants, and move deprecation warnings into the Note section of
the deprecated struct.

Replace 'OR:ed' with 'added', as the former looks odd.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
---

The replacement of 'OR:ed' should strictly be in a separate patch, as 
it isn't a formatting change, but as the same lines containing them were
being changed anyway it feels like overkill?

 include/uapi/linux/gpio.h | 93 ++++++++++++++++++++-------------------
 1 file changed, 47 insertions(+), 46 deletions(-)

diff --git a/include/uapi/linux/gpio.h b/include/uapi/linux/gpio.h
index 1fdb0e851f83..32dd18f238c3 100644
--- a/include/uapi/linux/gpio.h
+++ b/include/uapi/linux/gpio.h
@@ -110,17 +110,17 @@ enum gpio_v2_line_attr_id {
  * struct gpio_v2_line_attribute - a configurable attribute of a line
  * @id: attribute identifier with value from &enum gpio_v2_line_attr_id
  * @padding: reserved for future use and must be zero filled
- * @flags: if id is GPIO_V2_LINE_ATTR_ID_FLAGS, the flags for the GPIO
- * line, with values from enum gpio_v2_line_flag, such as
- * GPIO_V2_LINE_FLAG_ACTIVE_LOW, GPIO_V2_LINE_FLAG_OUTPUT etc, OR:ed
+ * @flags: if id is %GPIO_V2_LINE_ATTR_ID_FLAGS, the flags for the GPIO
+ * line, with values from &enum gpio_v2_line_flag, such as
+ * %GPIO_V2_LINE_FLAG_ACTIVE_LOW, %GPIO_V2_LINE_FLAG_OUTPUT etc, added
  * together.  This overrides the default flags contained in the &struct
  * gpio_v2_line_config for the associated line.
- * @values: if id is GPIO_V2_LINE_ATTR_ID_OUTPUT_VALUES, a bitmap
+ * @values: if id is %GPIO_V2_LINE_ATTR_ID_OUTPUT_VALUES, a bitmap
  * containing the values to which the lines will be set, with each bit
  * number corresponding to the index into &struct
  * gpio_v2_line_request.offsets.
- * @debounce_period_us: if id is GPIO_V2_LINE_ATTR_ID_DEBOUNCE, the desired
- * debounce period, in microseconds
+ * @debounce_period_us: if id is %GPIO_V2_LINE_ATTR_ID_DEBOUNCE, the
+ * desired debounce period, in microseconds
  */
 struct gpio_v2_line_attribute {
 	__u32 id;
@@ -147,12 +147,12 @@ struct gpio_v2_line_config_attribute {
 
 /**
  * struct gpio_v2_line_config - Configuration for GPIO lines
- * @flags: flags for the GPIO lines, with values from enum
- * gpio_v2_line_flag, such as GPIO_V2_LINE_FLAG_ACTIVE_LOW,
- * GPIO_V2_LINE_FLAG_OUTPUT etc, OR:ed together.  This is the default for
+ * @flags: flags for the GPIO lines, with values from &enum
+ * gpio_v2_line_flag, such as %GPIO_V2_LINE_FLAG_ACTIVE_LOW,
+ * %GPIO_V2_LINE_FLAG_OUTPUT etc, added together.  This is the default for
  * all requested lines but may be overridden for particular lines using
- * attrs.
- * @num_attrs: the number of attributes in attrs
+ * @attrs.
+ * @num_attrs: the number of attributes in @attrs
  * @padding: reserved for future use and must be zero filled
  * @attrs: the configuration attributes associated with the requested
  * lines.  Any attribute should only be associated with a particular line
@@ -175,17 +175,17 @@ struct gpio_v2_line_config {
  * "my-bitbanged-relay"
  * @config: requested configuration for the lines.
  * @num_lines: number of lines requested in this request, i.e. the number
- * of valid fields in the GPIO_V2_LINES_MAX sized arrays, set to 1 to
+ * of valid fields in the %GPIO_V2_LINES_MAX sized arrays, set to 1 to
  * request a single line
  * @event_buffer_size: a suggested minimum number of line events that the
  * kernel should buffer.  This is only relevant if edge detection is
  * enabled in the configuration. Note that this is only a suggested value
  * and the kernel may allocate a larger buffer or cap the size of the
  * buffer. If this field is zero then the buffer size defaults to a minimum
- * of num_lines*16.
+ * of @num_lines * 16.
  * @padding: reserved for future use and must be zero filled
  * @fd: if successful this field will contain a valid anonymous file handle
- * after a GPIO_GET_LINE_IOCTL operation, zero or negative value means
+ * after a %GPIO_GET_LINE_IOCTL operation, zero or negative value means
  * error
  */
 struct gpio_v2_line_request {
@@ -207,11 +207,12 @@ struct gpio_v2_line_request {
  * @consumer: a functional name for the consumer of this GPIO line as set
  * by whatever is using it, will be empty if there is no current user but
  * may also be empty if the consumer doesn't set this up
- * @flags: flags for the GPIO line, such as GPIO_V2_LINE_FLAG_ACTIVE_LOW,
- * GPIO_V2_LINE_FLAG_OUTPUT etc, OR:ed together
  * @offset: the local offset on this GPIO chip, fill this in when
  * requesting the line information from the kernel
- * @num_attrs: the number of attributes in attrs
+ * @num_attrs: the number of attributes in @attrs
+ * @flags: flags for the GPIO lines, with values from &enum
+ * gpio_v2_line_flag, such as %GPIO_V2_LINE_FLAG_ACTIVE_LOW,
+ * %GPIO_V2_LINE_FLAG_OUTPUT etc, added together.
  * @attrs: the configuration attributes associated with the line
  * @padding: reserved for future use
  */
@@ -244,7 +245,7 @@ enum gpio_v2_line_changed_type {
  * of a GPIO line
  * @info: updated line information
  * @timestamp_ns: estimate of time of status change occurrence, in nanoseconds
- * @event_type: the type of change with a value from enum
+ * @event_type: the type of change with a value from &enum
  * gpio_v2_line_changed_type
  * @padding: reserved for future use
  */
@@ -269,10 +270,10 @@ enum gpio_v2_line_event_id {
 /**
  * struct gpio_v2_line_event - The actual event being pushed to userspace
  * @timestamp_ns: best estimate of time of event occurrence, in nanoseconds.
- * The timestamp_ns is read from CLOCK_MONOTONIC and is intended to allow the
- * accurate measurement of the time between events.  It does not provide
+ * The @timestamp_ns is read from %CLOCK_MONOTONIC and is intended to allow
+ * the accurate measurement of the time between events. It does not provide
  * the wall-clock time.
- * @id: event identifier with value from enum gpio_v2_line_event_id
+ * @id: event identifier with value from &enum gpio_v2_line_event_id
  * @offset: the offset of the line that triggered the event
  * @seqno: the sequence number for this event in the sequence of events for
  * all the lines in this line request
@@ -319,8 +320,8 @@ struct gpio_v2_line_event {
  * whatever is using it, will be empty if there is no current user but may
  * also be empty if the consumer doesn't set this up
  *
- * This struct is part of ABI v1 and is deprecated.
- * Use struct gpio_v2_line_info instead.
+ * Note: This struct is part of ABI v1 and is deprecated.
+ * Use &struct gpio_v2_line_info instead.
  */
 struct gpioline_info {
 	__u32 line_offset;
@@ -344,18 +345,18 @@ enum {
  * of a GPIO line
  * @info: updated line information
  * @timestamp: estimate of time of status change occurrence, in nanoseconds
- * @event_type: one of GPIOLINE_CHANGED_REQUESTED, GPIOLINE_CHANGED_RELEASED
- * and GPIOLINE_CHANGED_CONFIG
+ * @event_type: one of %GPIOLINE_CHANGED_REQUESTED,
+ * %GPIOLINE_CHANGED_RELEASED and %GPIOLINE_CHANGED_CONFIG
  * @padding: reserved for future use
  *
- * Note: struct gpioline_info embedded here has 32-bit alignment on its own,
+ * The &struct gpioline_info embedded here has 32-bit alignment on its own,
  * but it works fine with 64-bit alignment too. With its 72 byte size, we can
  * guarantee there are no implicit holes between it and subsequent members.
  * The 20-byte padding at the end makes sure we don't add any implicit padding
  * at the end of the structure on 64-bit architectures.
  *
- * This struct is part of ABI v1 and is deprecated.
- * Use struct gpio_v2_line_info_changed instead.
+ * Note: This struct is part of ABI v1 and is deprecated.
+ * Use &struct gpio_v2_line_info_changed instead.
  */
 struct gpioline_info_changed {
 	struct gpioline_info info;
@@ -379,13 +380,13 @@ struct gpioline_info_changed {
  * @lineoffsets: an array of desired lines, specified by offset index for the
  * associated GPIO device
  * @flags: desired flags for the desired GPIO lines, such as
- * GPIOHANDLE_REQUEST_OUTPUT, GPIOHANDLE_REQUEST_ACTIVE_LOW etc, OR:ed
+ * %GPIOHANDLE_REQUEST_OUTPUT, %GPIOHANDLE_REQUEST_ACTIVE_LOW etc, added
  * together. Note that even if multiple lines are requested, the same flags
  * must be applicable to all of them, if you want lines with individual
  * flags set, request them one by one. It is possible to select
  * a batch of input or output lines, but they must all have the same
  * characteristics, i.e. all inputs or all outputs, all active low etc
- * @default_values: if the GPIOHANDLE_REQUEST_OUTPUT is set for a requested
+ * @default_values: if the %GPIOHANDLE_REQUEST_OUTPUT is set for a requested
  * line, this specifies the default output value, should be 0 (low) or
  * 1 (high), anything else than 0 or 1 will be interpreted as 1 (high)
  * @consumer_label: a desired consumer label for the selected GPIO line(s)
@@ -393,11 +394,11 @@ struct gpioline_info_changed {
  * @lines: number of lines requested in this request, i.e. the number of
  * valid fields in the above arrays, set to 1 to request a single line
  * @fd: if successful this field will contain a valid anonymous file handle
- * after a GPIO_GET_LINEHANDLE_IOCTL operation, zero or negative value
+ * after a %GPIO_GET_LINEHANDLE_IOCTL operation, zero or negative value
  * means error
  *
- * This struct is part of ABI v1 and is deprecated.
- * Use struct gpio_v2_line_request instead.
+ * Note: This struct is part of ABI v1 and is deprecated.
+ * Use &struct gpio_v2_line_request instead.
  */
 struct gpiohandle_request {
 	__u32 lineoffsets[GPIOHANDLES_MAX];
@@ -411,15 +412,15 @@ struct gpiohandle_request {
 /**
  * struct gpiohandle_config - Configuration for a GPIO handle request
  * @flags: updated flags for the requested GPIO lines, such as
- * GPIOHANDLE_REQUEST_OUTPUT, GPIOHANDLE_REQUEST_ACTIVE_LOW etc, OR:ed
+ * %GPIOHANDLE_REQUEST_OUTPUT, %GPIOHANDLE_REQUEST_ACTIVE_LOW etc, added
  * together
- * @default_values: if the GPIOHANDLE_REQUEST_OUTPUT is set in flags,
+ * @default_values: if the %GPIOHANDLE_REQUEST_OUTPUT is set in flags,
  * this specifies the default output value, should be 0 (low) or
  * 1 (high), anything else than 0 or 1 will be interpreted as 1 (high)
  * @padding: reserved for future use and should be zero filled
  *
- * This struct is part of ABI v1 and is deprecated.
- * Use struct gpio_v2_line_config instead.
+ * Note: This struct is part of ABI v1 and is deprecated.
+ * Use &struct gpio_v2_line_config instead.
  */
 struct gpiohandle_config {
 	__u32 flags;
@@ -433,8 +434,8 @@ struct gpiohandle_config {
  * state of a line, when setting the state of lines these should contain
  * the desired target state
  *
- * This struct is part of ABI v1 and is deprecated.
- * Use struct gpio_v2_line_values instead.
+ * Note: This struct is part of ABI v1 and is deprecated.
+ * Use &struct gpio_v2_line_values instead.
  */
 struct gpiohandle_data {
 	__u8 values[GPIOHANDLES_MAX];
@@ -450,17 +451,17 @@ struct gpiohandle_data {
  * @lineoffset: the desired line to subscribe to events from, specified by
  * offset index for the associated GPIO device
  * @handleflags: desired handle flags for the desired GPIO line, such as
- * GPIOHANDLE_REQUEST_ACTIVE_LOW or GPIOHANDLE_REQUEST_OPEN_DRAIN
+ * %GPIOHANDLE_REQUEST_ACTIVE_LOW or %GPIOHANDLE_REQUEST_OPEN_DRAIN
  * @eventflags: desired flags for the desired GPIO event line, such as
- * GPIOEVENT_REQUEST_RISING_EDGE or GPIOEVENT_REQUEST_FALLING_EDGE
+ * %GPIOEVENT_REQUEST_RISING_EDGE or %GPIOEVENT_REQUEST_FALLING_EDGE
  * @consumer_label: a desired consumer label for the selected GPIO line(s)
  * such as "my-listener"
  * @fd: if successful this field will contain a valid anonymous file handle
- * after a GPIO_GET_LINEEVENT_IOCTL operation, zero or negative value
+ * after a %GPIO_GET_LINEEVENT_IOCTL operation, zero or negative value
  * means error
  *
- * This struct is part of ABI v1 and is deprecated.
- * Use struct gpio_v2_line_request instead.
+ * Note: This struct is part of ABI v1 and is deprecated.
+ * Use &struct gpio_v2_line_request instead.
  */
 struct gpioevent_request {
 	__u32 lineoffset;
@@ -481,8 +482,8 @@ struct gpioevent_request {
  * @timestamp: best estimate of time of event occurrence, in nanoseconds
  * @id: event identifier
  *
- * This struct is part of ABI v1 and is deprecated.
- * Use struct gpio_v2_line_event instead.
+ * Note: This struct is part of ABI v1 and is deprecated.
+ * Use &struct gpio_v2_line_event instead.
  */
 struct gpioevent_data {
 	__u64 timestamp;
-- 
2.28.0

[PATCH 4/5] gpio: uapi: remove whitespace

[Kent Gibson]

Remove leading whitespace in ABI v1 comment.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
---
 include/uapi/linux/gpio.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/uapi/linux/gpio.h b/include/uapi/linux/gpio.h
index 32dd18f238c3..ad3f56dd87ec 100644
--- a/include/uapi/linux/gpio.h
+++ b/include/uapi/linux/gpio.h
@@ -292,7 +292,7 @@ struct gpio_v2_line_event {
 };
 
 /*
- *  ABI v1
+ * ABI v1
  *
  * This version of the ABI is deprecated.
  * Use the latest version of the ABI, defined above, instead.
-- 
2.28.0

[PATCH 5/5] gpio: uapi: clarify the meaning of 'empty' char arrays

[Kent Gibson]

Clarify that a char array containing a string is considered 'empty' if
the first character is the null terminator. The remaining characters
are not relevant to this determination.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
---
 include/uapi/linux/gpio.h | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/include/uapi/linux/gpio.h b/include/uapi/linux/gpio.h
index ad3f56dd87ec..2072c260f5d0 100644
--- a/include/uapi/linux/gpio.h
+++ b/include/uapi/linux/gpio.h
@@ -26,7 +26,7 @@
  * struct gpiochip_info - Information about a certain GPIO chip
  * @name: the Linux kernel name of this GPIO chip
  * @label: a functional name for this GPIO chip, such as a product
- * number, may be empty
+ * number, may be empty (i.e. label[0] == '\0')
  * @lines: number of GPIO lines on this chip
  */
 struct gpiochip_info {
@@ -203,7 +203,7 @@ struct gpio_v2_line_request {
  * struct gpio_v2_line_info - Information about a certain GPIO line
  * @name: the name of this GPIO line, such as the output pin of the line on
  * the chip, a rail or a pin header name on a board, as specified by the
- * GPIO chip, may be empty
+ * GPIO chip, may be empty (i.e. name[0] == '\0')
  * @consumer: a functional name for the consumer of this GPIO line as set
  * by whatever is using it, will be empty if there is no current user but
  * may also be empty if the consumer doesn't set this up
@@ -315,7 +315,7 @@ struct gpio_v2_line_event {
  * @flags: various flags for this line
  * @name: the name of this GPIO line, such as the output pin of the line on the
  * chip, a rail or a pin header name on a board, as specified by the gpio
- * chip, may be empty
+ * chip, may be empty (i.e. name[0] == '\0')
  * @consumer: a functional name for the consumer of this GPIO line as set by
  * whatever is using it, will be empty if there is no current user but may
  * also be empty if the consumer doesn't set this up
-- 
2.28.0

Re: [PATCH 5/5] gpio: uapi: clarify the meaning of 'empty' char arrays

[Andy Shevchenko]

On Mon, Oct 5, 2020 at 10:07 AM Kent Gibson <warthog618@gmail.com> wrote:
>
> Clarify that a char array containing a string is considered 'empty' if
> the first character is the null terminator. The remaining characters
> are not relevant to this determination.

>   * @label: a functional name for this GPIO chip, such as a product
> - * number, may be empty
> + * number, may be empty (i.e. label[0] == '\0')

I would rather put it like
"...may be empty string (i.e. label == "")"

And so on for the rest.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH 0/5] gpio: uapi: documentation improvements

[Andy Shevchenko]

On Mon, Oct 5, 2020 at 10:04 AM Kent Gibson <warthog618@gmail.com> wrote:
>
> I'm intending to add some GPIO chardev documentation to
> Documentation/admin-guide/gpio/chardev.rst (or perhaps
> Documentation/userspace-api/??), but that is taking longer than I'd like,
> so in the meantime here is a collection of minor documentation tidy-ups
> and improvements to the kernel-doc that I've made along the way.
> Hopefully nothing controversial - mainly formatting improvements,
> and a couple of minor wording changes.

Thanks.
For patches 1-4
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>

Patch 5 as well in case you agree with my comments and goind

>
> Cheers,
> Kent.
>
> Kent Gibson (5):
>   gpio: uapi: fix kernel-doc warnings
>   gpio: uapi: comment consistency
>   gpio: uapi: kernel-doc formatting improvements
>   gpio: uapi: remove whitespace
>   gpio: uapi: clarify the meaning of 'empty' char arrays
>
>  include/uapi/linux/gpio.h | 106 +++++++++++++++++++-------------------
>  1 file changed, 54 insertions(+), 52 deletions(-)
>
>
> base-commit: 237d96164f2c2b33d0d5094192eb743e9e1b04ad
> --
> 2.28.0
>


-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH 0/5] gpio: uapi: documentation improvements

[Andy Shevchenko]

On Mon, Oct 5, 2020 at 2:02 PM Andy Shevchenko
<andy.shevchenko@gmail.com> wrote:
> On Mon, Oct 5, 2020 at 10:04 AM Kent Gibson <warthog618@gmail.com> wrote:

> Patch 5 as well in case you agree with my comments and goind

and going to address them.


-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH 5/5] gpio: uapi: clarify the meaning of 'empty' char arrays

[Kent Gibson]

On Mon, Oct 05, 2020 at 02:01:22PM +0300, Andy Shevchenko wrote:
> On Mon, Oct 5, 2020 at 10:07 AM Kent Gibson <warthog618@gmail.com> wrote:
> >
> > Clarify that a char array containing a string is considered 'empty' if
> > the first character is the null terminator. The remaining characters
> > are not relevant to this determination.
> 
> >   * @label: a functional name for this GPIO chip, such as a product
> > - * number, may be empty
> > + * number, may be empty (i.e. label[0] == '\0')
> 
> I would rather put it like
> "...may be empty string (i.e. label == "")"
> 

I'm not keen on that alternative as what it suggests is actually a
pointer comparison, and even if the user realizes that they may instead
use "strlen(label) == 0", when they shouldn't be assuming that a null
terminator is present in the array.  I avoided mentioning "string" and
kept it in terms of the char array for the same reason.

Cheers,
Kent.

Re: [PATCH 0/5] gpio: uapi: documentation improvements

[Bartosz Golaszewski]

On Mon, Oct 5, 2020 at 9:03 AM Kent Gibson <warthog618@gmail.com> wrote:
>
> I'm intending to add some GPIO chardev documentation to
> Documentation/admin-guide/gpio/chardev.rst (or perhaps
> Documentation/userspace-api/??), but that is taking longer than I'd like,
> so in the meantime here is a collection of minor documentation tidy-ups
> and improvements to the kernel-doc that I've made along the way.
> Hopefully nothing controversial - mainly formatting improvements,
> and a couple of minor wording changes.
>
> Cheers,
> Kent.
>
> Kent Gibson (5):
>   gpio: uapi: fix kernel-doc warnings
>   gpio: uapi: comment consistency
>   gpio: uapi: kernel-doc formatting improvements
>   gpio: uapi: remove whitespace
>   gpio: uapi: clarify the meaning of 'empty' char arrays
>
>  include/uapi/linux/gpio.h | 106 +++++++++++++++++++-------------------
>  1 file changed, 54 insertions(+), 52 deletions(-)
>
>
> base-commit: 237d96164f2c2b33d0d5094192eb743e9e1b04ad
> --
> 2.28.0
>

For the entire series:

Reviewed-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

Linus: can you take them for v5.10 through your tree directly?

Bartosz

Re: [PATCH 0/5] gpio: uapi: documentation improvements

[Linus Walleij]

On Thu, Oct 8, 2020 at 5:46 PM Bartosz Golaszewski
<bgolaszewski@baylibre.com> wrote:
> On Mon, Oct 5, 2020 at 9:03 AM Kent Gibson <warthog618@gmail.com> wrote:
> >
> > I'm intending to add some GPIO chardev documentation to
> > Documentation/admin-guide/gpio/chardev.rst (or perhaps
> > Documentation/userspace-api/??), but that is taking longer than I'd like,
> > so in the meantime here is a collection of minor documentation tidy-ups
> > and improvements to the kernel-doc that I've made along the way.
> > Hopefully nothing controversial - mainly formatting improvements,
> > and a couple of minor wording changes.

> For the entire series:
>
> Reviewed-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
>
> Linus: can you take them for v5.10 through your tree directly?

I am waiting for Kent to respin them addressing Andy's comments
on patch 5/5 then they can go in as fixes I think.

Yours,
Linus Walleij

Re: [PATCH 0/5] gpio: uapi: documentation improvements

[Kent Gibson]

On Tue, Oct 13, 2020 at 03:21:47PM +0200, Linus Walleij wrote:
> On Thu, Oct 8, 2020 at 5:46 PM Bartosz Golaszewski
> <bgolaszewski@baylibre.com> wrote:
> > On Mon, Oct 5, 2020 at 9:03 AM Kent Gibson <warthog618@gmail.com> wrote:
> > >
> > > I'm intending to add some GPIO chardev documentation to
> > > Documentation/admin-guide/gpio/chardev.rst (or perhaps
> > > Documentation/userspace-api/??), but that is taking longer than I'd like,
> > > so in the meantime here is a collection of minor documentation tidy-ups
> > > and improvements to the kernel-doc that I've made along the way.
> > > Hopefully nothing controversial - mainly formatting improvements,
> > > and a couple of minor wording changes.
> 
> > For the entire series:
> >
> > Reviewed-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
> >
> > Linus: can you take them for v5.10 through your tree directly?
> 
> I am waiting for Kent to respin them addressing Andy's comments
> on patch 5/5 then they can go in as fixes I think.
> 

I had replied to Andy's comments - I'm prefer with my version than his
suggestion:

"I'm not keen on that alternative as what it suggests is actually a
pointer comparison, and even if the user realizes that they may instead
use "strlen(label) == 0", when they shouldn't be assuming that a null
terminator is present in the array.  I avoided mentioning "string" and
kept it in terms of the char array for the same reason."

Cheers,
Kent.

Re: [PATCH 0/5] gpio: uapi: documentation improvements

[Andy Shevchenko]

On Tue, Oct 13, 2020 at 7:34 PM Kent Gibson <warthog618@gmail.com> wrote:
> On Tue, Oct 13, 2020 at 03:21:47PM +0200, Linus Walleij wrote:
> > On Thu, Oct 8, 2020 at 5:46 PM Bartosz Golaszewski
> > <bgolaszewski@baylibre.com> wrote:

...

> > I am waiting for Kent to respin them addressing Andy's comments
> > on patch 5/5 then they can go in as fixes I think.
> >
>
> I had replied to Andy's comments - I'm prefer with my version than his
> suggestion:
>
> "I'm not keen on that alternative as what it suggests is actually a
> pointer comparison, and even if the user realizes that they may instead
> use "strlen(label) == 0", when they shouldn't be assuming that a null
> terminator is present in the array.  I avoided mentioning "string" and
> kept it in terms of the char array for the same reason."

My point is to make documentation less cryptic (= less programming
language stylish).
If you can rephrase it that way - nice! Otherwise, I leave this to Linus.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH 0/5] gpio: uapi: documentation improvements

[Kent Gibson]

On Wed, Oct 14, 2020 at 08:14:20PM +0300, Andy Shevchenko wrote:
> On Tue, Oct 13, 2020 at 7:34 PM Kent Gibson <warthog618@gmail.com> wrote:
> > On Tue, Oct 13, 2020 at 03:21:47PM +0200, Linus Walleij wrote:
> > > On Thu, Oct 8, 2020 at 5:46 PM Bartosz Golaszewski
> > > <bgolaszewski@baylibre.com> wrote:
> 
> ...
> 
> > > I am waiting for Kent to respin them addressing Andy's comments
> > > on patch 5/5 then they can go in as fixes I think.
> > >
> >
> > I had replied to Andy's comments - I'm prefer with my version than his
> > suggestion:
> >
> > "I'm not keen on that alternative as what it suggests is actually a
> > pointer comparison, and even if the user realizes that they may instead
> > use "strlen(label) == 0", when they shouldn't be assuming that a null
> > terminator is present in the array.  I avoided mentioning "string" and
> > kept it in terms of the char array for the same reason."
> 
> My point is to make documentation less cryptic (= less programming
> language stylish).
> If you can rephrase it that way - nice! Otherwise, I leave this to Linus.
> 

I agree with your point - including code snippets should be a last
resort. But sometimes that is the most effective way to do it.

Cheers,
Kent.

Re: [PATCH 0/5] gpio: uapi: documentation improvements

[Linus Walleij]

On Mon, Oct 5, 2020 at 9:03 AM Kent Gibson <warthog618@gmail.com> wrote:

> Kent Gibson (5):
>   gpio: uapi: fix kernel-doc warnings
>   gpio: uapi: comment consistency
>   gpio: uapi: kernel-doc formatting improvements
>   gpio: uapi: remove whitespace
>   gpio: uapi: clarify the meaning of 'empty' char arrays

I applied this to my fixes branch now. Thanks!

Yours,
Linus Walleij