* [PATCH 0/5] gpio: uapi: documentation improvements
@ 2020-10-05 7:03 Kent Gibson
2020-10-05 7:03 ` [PATCH 1/5] gpio: uapi: fix kernel-doc warnings Kent Gibson
` (7 more replies)
0 siblings, 8 replies; 16+ messages in thread
From: Kent Gibson @ 2020-10-05 7:03 UTC (permalink / raw)
To: linux-kernel, linux-gpio, bgolaszewski, linus.walleij; +Cc: 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
^ permalink raw reply [flat|nested] 16+ messages in thread* [PATCH 1/5] gpio: uapi: fix kernel-doc warnings 2020-10-05 7:03 [PATCH 0/5] gpio: uapi: documentation improvements Kent Gibson @ 2020-10-05 7:03 ` Kent Gibson 2020-10-05 7:03 ` [PATCH 2/5] gpio: uapi: comment consistency Kent Gibson ` (6 subsequent siblings) 7 siblings, 0 replies; 16+ messages in thread From: Kent Gibson @ 2020-10-05 7:03 UTC (permalink / raw) To: linux-kernel, linux-gpio, bgolaszewski, linus.walleij; +Cc: 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 ^ permalink raw reply related [flat|nested] 16+ messages in thread
* [PATCH 2/5] gpio: uapi: comment consistency 2020-10-05 7:03 [PATCH 0/5] gpio: uapi: documentation improvements Kent Gibson 2020-10-05 7:03 ` [PATCH 1/5] gpio: uapi: fix kernel-doc warnings Kent Gibson @ 2020-10-05 7:03 ` Kent Gibson 2020-10-05 7:03 ` [PATCH 3/5] gpio: uapi: kernel-doc formatting improvements Kent Gibson ` (5 subsequent siblings) 7 siblings, 0 replies; 16+ messages in thread From: Kent Gibson @ 2020-10-05 7:03 UTC (permalink / raw) To: linux-kernel, linux-gpio, bgolaszewski, linus.walleij; +Cc: 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 ^ permalink raw reply related [flat|nested] 16+ messages in thread
* [PATCH 3/5] gpio: uapi: kernel-doc formatting improvements 2020-10-05 7:03 [PATCH 0/5] gpio: uapi: documentation improvements Kent Gibson 2020-10-05 7:03 ` [PATCH 1/5] gpio: uapi: fix kernel-doc warnings Kent Gibson 2020-10-05 7:03 ` [PATCH 2/5] gpio: uapi: comment consistency Kent Gibson @ 2020-10-05 7:03 ` Kent Gibson 2020-10-05 7:03 ` [PATCH 4/5] gpio: uapi: remove whitespace Kent Gibson ` (4 subsequent siblings) 7 siblings, 0 replies; 16+ messages in thread From: Kent Gibson @ 2020-10-05 7:03 UTC (permalink / raw) To: linux-kernel, linux-gpio, bgolaszewski, linus.walleij; +Cc: 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 ^ permalink raw reply related [flat|nested] 16+ messages in thread
* [PATCH 4/5] gpio: uapi: remove whitespace 2020-10-05 7:03 [PATCH 0/5] gpio: uapi: documentation improvements Kent Gibson ` (2 preceding siblings ...) 2020-10-05 7:03 ` [PATCH 3/5] gpio: uapi: kernel-doc formatting improvements Kent Gibson @ 2020-10-05 7:03 ` Kent Gibson 2020-10-05 7:03 ` [PATCH 5/5] gpio: uapi: clarify the meaning of 'empty' char arrays Kent Gibson ` (3 subsequent siblings) 7 siblings, 0 replies; 16+ messages in thread From: Kent Gibson @ 2020-10-05 7:03 UTC (permalink / raw) To: linux-kernel, linux-gpio, bgolaszewski, linus.walleij; +Cc: 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 ^ permalink raw reply related [flat|nested] 16+ messages in thread
* [PATCH 5/5] gpio: uapi: clarify the meaning of 'empty' char arrays 2020-10-05 7:03 [PATCH 0/5] gpio: uapi: documentation improvements Kent Gibson ` (3 preceding siblings ...) 2020-10-05 7:03 ` [PATCH 4/5] gpio: uapi: remove whitespace Kent Gibson @ 2020-10-05 7:03 ` Kent Gibson 2020-10-05 11:01 ` Andy Shevchenko 2020-10-05 11:02 ` [PATCH 0/5] gpio: uapi: documentation improvements Andy Shevchenko ` (2 subsequent siblings) 7 siblings, 1 reply; 16+ messages in thread From: Kent Gibson @ 2020-10-05 7:03 UTC (permalink / raw) To: linux-kernel, linux-gpio, bgolaszewski, linus.walleij; +Cc: 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 ^ permalink raw reply related [flat|nested] 16+ messages in thread
* Re: [PATCH 5/5] gpio: uapi: clarify the meaning of 'empty' char arrays 2020-10-05 7:03 ` [PATCH 5/5] gpio: uapi: clarify the meaning of 'empty' char arrays Kent Gibson @ 2020-10-05 11:01 ` Andy Shevchenko 2020-10-05 13:06 ` Kent Gibson 0 siblings, 1 reply; 16+ messages in thread From: Andy Shevchenko @ 2020-10-05 11:01 UTC (permalink / raw) To: Kent Gibson Cc: Linux Kernel Mailing List, open list:GPIO SUBSYSTEM, Bartosz Golaszewski, Linus Walleij 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [PATCH 5/5] gpio: uapi: clarify the meaning of 'empty' char arrays 2020-10-05 11:01 ` Andy Shevchenko @ 2020-10-05 13:06 ` Kent Gibson 0 siblings, 0 replies; 16+ messages in thread From: Kent Gibson @ 2020-10-05 13:06 UTC (permalink / raw) To: Andy Shevchenko Cc: Linux Kernel Mailing List, open list:GPIO SUBSYSTEM, Bartosz Golaszewski, Linus Walleij 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. ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [PATCH 0/5] gpio: uapi: documentation improvements 2020-10-05 7:03 [PATCH 0/5] gpio: uapi: documentation improvements Kent Gibson ` (4 preceding siblings ...) 2020-10-05 7:03 ` [PATCH 5/5] gpio: uapi: clarify the meaning of 'empty' char arrays Kent Gibson @ 2020-10-05 11:02 ` Andy Shevchenko 2020-10-05 11:02 ` Andy Shevchenko 2020-10-08 15:46 ` Bartosz Golaszewski 2020-10-19 13:05 ` Linus Walleij 7 siblings, 1 reply; 16+ messages in thread From: Andy Shevchenko @ 2020-10-05 11:02 UTC (permalink / raw) To: Kent Gibson Cc: Linux Kernel Mailing List, open list:GPIO SUBSYSTEM, Bartosz Golaszewski, Linus Walleij 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [PATCH 0/5] gpio: uapi: documentation improvements 2020-10-05 11:02 ` [PATCH 0/5] gpio: uapi: documentation improvements Andy Shevchenko @ 2020-10-05 11:02 ` Andy Shevchenko 0 siblings, 0 replies; 16+ messages in thread From: Andy Shevchenko @ 2020-10-05 11:02 UTC (permalink / raw) To: Kent Gibson Cc: Linux Kernel Mailing List, open list:GPIO SUBSYSTEM, Bartosz Golaszewski, Linus Walleij 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [PATCH 0/5] gpio: uapi: documentation improvements 2020-10-05 7:03 [PATCH 0/5] gpio: uapi: documentation improvements Kent Gibson ` (5 preceding siblings ...) 2020-10-05 11:02 ` [PATCH 0/5] gpio: uapi: documentation improvements Andy Shevchenko @ 2020-10-08 15:46 ` Bartosz Golaszewski 2020-10-13 13:21 ` Linus Walleij 2020-10-19 13:05 ` Linus Walleij 7 siblings, 1 reply; 16+ messages in thread From: Bartosz Golaszewski @ 2020-10-08 15:46 UTC (permalink / raw) To: Kent Gibson; +Cc: LKML, linux-gpio, Linus Walleij 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [PATCH 0/5] gpio: uapi: documentation improvements 2020-10-08 15:46 ` Bartosz Golaszewski @ 2020-10-13 13:21 ` Linus Walleij 2020-10-13 13:29 ` Kent Gibson 0 siblings, 1 reply; 16+ messages in thread From: Linus Walleij @ 2020-10-13 13:21 UTC (permalink / raw) To: Bartosz Golaszewski; +Cc: Kent Gibson, LKML, linux-gpio 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [PATCH 0/5] gpio: uapi: documentation improvements 2020-10-13 13:21 ` Linus Walleij @ 2020-10-13 13:29 ` Kent Gibson 2020-10-14 17:14 ` Andy Shevchenko 0 siblings, 1 reply; 16+ messages in thread From: Kent Gibson @ 2020-10-13 13:29 UTC (permalink / raw) To: Linus Walleij; +Cc: Bartosz Golaszewski, LKML, linux-gpio 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. ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [PATCH 0/5] gpio: uapi: documentation improvements 2020-10-13 13:29 ` Kent Gibson @ 2020-10-14 17:14 ` Andy Shevchenko 2020-10-14 23:35 ` Kent Gibson 0 siblings, 1 reply; 16+ messages in thread From: Andy Shevchenko @ 2020-10-14 17:14 UTC (permalink / raw) To: Kent Gibson; +Cc: Linus Walleij, Bartosz Golaszewski, LKML, linux-gpio 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [PATCH 0/5] gpio: uapi: documentation improvements 2020-10-14 17:14 ` Andy Shevchenko @ 2020-10-14 23:35 ` Kent Gibson 0 siblings, 0 replies; 16+ messages in thread From: Kent Gibson @ 2020-10-14 23:35 UTC (permalink / raw) To: Andy Shevchenko; +Cc: Linus Walleij, Bartosz Golaszewski, LKML, linux-gpio 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. ^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [PATCH 0/5] gpio: uapi: documentation improvements 2020-10-05 7:03 [PATCH 0/5] gpio: uapi: documentation improvements Kent Gibson ` (6 preceding siblings ...) 2020-10-08 15:46 ` Bartosz Golaszewski @ 2020-10-19 13:05 ` Linus Walleij 7 siblings, 0 replies; 16+ messages in thread From: Linus Walleij @ 2020-10-19 13:05 UTC (permalink / raw) To: Kent Gibson; +Cc: linux-kernel, open list:GPIO SUBSYSTEM, Bartosz Golaszewski 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 ^ permalink raw reply [flat|nested] 16+ messages in thread
end of thread, other threads:[~2020-10-19 13:05 UTC | newest] Thread overview: 16+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2020-10-05 7:03 [PATCH 0/5] gpio: uapi: documentation improvements Kent Gibson 2020-10-05 7:03 ` [PATCH 1/5] gpio: uapi: fix kernel-doc warnings Kent Gibson 2020-10-05 7:03 ` [PATCH 2/5] gpio: uapi: comment consistency Kent Gibson 2020-10-05 7:03 ` [PATCH 3/5] gpio: uapi: kernel-doc formatting improvements Kent Gibson 2020-10-05 7:03 ` [PATCH 4/5] gpio: uapi: remove whitespace Kent Gibson 2020-10-05 7:03 ` [PATCH 5/5] gpio: uapi: clarify the meaning of 'empty' char arrays Kent Gibson 2020-10-05 11:01 ` Andy Shevchenko 2020-10-05 13:06 ` Kent Gibson 2020-10-05 11:02 ` [PATCH 0/5] gpio: uapi: documentation improvements Andy Shevchenko 2020-10-05 11:02 ` Andy Shevchenko 2020-10-08 15:46 ` Bartosz Golaszewski 2020-10-13 13:21 ` Linus Walleij 2020-10-13 13:29 ` Kent Gibson 2020-10-14 17:14 ` Andy Shevchenko 2020-10-14 23:35 ` Kent Gibson 2020-10-19 13:05 ` Linus Walleij
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).