gpiolib: make struct comments into real kernel docs
PATCH 1/1 gpiolib: make struct comments into real kernel docs
We have several comments that start with '/**' but don't conform to the kernel doc standard. Add proper detailed descriptions for the affected definitions and move the docs from the forward declarations to the struct definitions where applicable.
--- drivers/gpio/gpiolib.h | 31 +++++++++++++++++++++++++++++++ include/linux/gpio/consumer.h | 35 ++++++++++++++++------------------- 2 files changed, 47 insertions(+), 19 deletions(-)
drivers/gpio/gpiolib.h +31 -0
@@ -72,6 +72,20 @@ struct gpio_device {/* gpio suffixes used for ACPI and device tree lookup */ static __maybe_unused const char *const gpio_suffixes[] = {"gpios" ,"gpio" }; +/** +* struct gpio_array - Opaque descriptor for a structure of GPIO array attributes +* +* @desc: Array of pointers to the GPIO descriptors +* @size: Number of elements in desc +* @chip: Parent GPIO chip +* @get_mask: Get mask used in fastpath. +* @set_mask: Set mask used in fastpath. +* @invert_mask: Invert mask used in fastpath. +* +* This structure is attached to struct gpiod_descs obtained from +* gpiod_get_array() and can be passed back to get/set array functions in order +* to activate fast processing path if applicable. +*/ struct gpio_array {struct gpio_desc **desc;unsigned int size;
@@ -96,6 +110,23 @@ int gpiod_set_array_value_complex(bool raw, bool can_sleep,extern spinlock_t gpio_lock;extern struct list_head gpio_devices; + +/** +* struct gpio_desc - Opaque descriptor for a GPIO +* +* @gdev: Pointer to the parent GPIO device +* @flags: Binary descriptor flags +* @label: Name of the consumer +* @name: Line name +* @hog: Pointer to the device node that hogs this line (if any) +* @debounce_period_us: Debounce period in microseconds +* +* These are obtained using gpiod_get() and are preferable to the old +* integer-based handles. +* +* Contrary to integers, a pointer to a gpio_desc is guaranteed to be valid +* until the GPIO is released. +*/ struct gpio_desc {struct gpio_device *gdev;unsigned long flags;
include/linux/gpio/consumer.h +16 -19
@@ -8,27 +8,16 @@#include <linux/err.h> struct device ; - -/** -* Opaque descriptor for a GPIO. These are obtained using gpiod_get() and are -* preferable to the old integer-based handles. -* -* Contrary to integers, a pointer to a gpio_desc is guaranteed to be valid -* until the GPIO is released. -*/ struct gpio_desc ; - -/** -* Opaque descriptor for a structure of GPIO array attributes. This structure -* is attached to struct gpiod_descs obtained from gpiod_get_array() and can be -* passed back to get/set array functions in order to activate fast processing -* path if applicable. -*/ struct gpio_array ;/** -* Struct containing an array of descriptors that can be obtained using -* gpiod_get_array(). +* struct gpio_descs - Struct containing an array of descriptors that can be +* obtained using gpiod_get_array() +* +* @info: Pointer to the opaque gpio_array structure +* @ndescs: Number of held descriptors +* desc: Array of pointers to GPIO descriptors */ struct gpio_descs {struct gpio_array *info;
@@ -43,8 +32,16 @@ struct gpio_descs {#define GPIOD_FLAGS_BIT_NONEXCLUSIVE BIT(4)/** -* Optional flags that can be passed to one of gpiod_* to configure direction -* and output value. These values cannot be OR'd. +* enum gpiod_flags - Optional flags that can be passed to one of gpiod_* to +* configure direction and output value. These values +* cannot be OR'd. +* +* @GPIOD_ASIS: Don't change the direction +* @GPIOD_IN: Set lines to input mode +* @GPIOD_OUT_LOW: Set lines to output and drive them low +* @GPIOD_OUT_HIGH: Set lines to output and drive them high +* @GPIOD_OUT_LOW_OPEN_DRAIN: Set lines to open-drain output and drive them low +* @GPIOD_OUT_HIGH_OPEN_DRAIN: Set lines to open-drain output and drive them high */ enum gpiod_flags {GPIOD_ASIS =0 ,
Signature · 1 line
2.30.1
Quoted 4 lines · Bartosz Golaszewski
We have several comments that start with '/**' but don't conform to the kernel doc standard. Add proper detailed descriptions for the affected definitions and move the docs from the forward declarations to the struct definitions where applicable.
A few comments below.
Quoted 12 lines
Reported-by Randy Dunlap <[email protected]>Signed-off-by Bartosz Golaszewski <[email protected]>--- drivers/gpio/gpiolib.h | 31 +++++++++++++++++++++++++++++++ include/linux/gpio/consumer.h | 35 ++++++++++++++++------------------- 2 files changed, 47 insertions(+), 19 deletions(-)drivers/gpio/gpiolib.h +0
-0
drivers/gpio/gpiolib.h struct gpio_device { · line 78
Quoted 7 lines
drivers/gpio/gpiolib.h +3
-0@@ -72,6 +72,20 @@ struct gpio_device {/* gpio suffixes used for ACPI and device tree lookup */ static __maybe_unused const char *const gpio_suffixes[] = {"gpios" ,"gpio" }; +/** +* struct gpio_array - Opaque descriptor for a structure of GPIO array attributes +*
I dunno we need these blank lines.
drivers/gpio/gpiolib.h struct gpio_device { · line 79
Quoted 2 lines
drivers/gpio/gpiolib.h +2
-0+* @desc: Array of pointers to the GPIO descriptors +* @size: Number of elements in desc
in @desc
or
in the array of the descriptor pointers
drivers/gpio/gpiolib.h struct gpio_device { · line 83
Quoted 4 lines
drivers/gpio/gpiolib.h +4
-0+* @chip: Parent GPIO chip +* @get_mask: Get mask used in fastpath. +* @set_mask: Set mask used in fastpath. +* @invert_mask: Invert mask used in fastpath.
Why some of the descriptions are with grammar period and some w/o?
Quoted 17 lines
drivers/gpio/gpiolib.h +5
-0+* +* This structure is attached to struct gpiod_descs obtained from +* gpiod_get_array() and can be passed back to get/set array functions in order +* to activate fast processing path if applicable. +*/ struct gpio_array {struct gpio_desc **desc;drivers/gpio/gpiolib.h +5
-0unsigned int size;@@ -96,6 +110,23 @@ int gpiod_set_array_value_complex(bool raw, bool can_sleep,extern spinlock_t gpio_lock;extern struct list_head gpio_devices; + +/** +* struct gpio_desc - Opaque descriptor for a GPIO +* +* @gdev: Pointer to the parent GPIO device
drivers/gpio/gpiolib.h int gpiod_set_array_value_complex(bool raw, bool can_sleep, · line 127
Quoted 10 lines
drivers/gpio/gpiolib.h +10
-0+* @flags: Binary descriptor flags +* @label: Name of the consumer +* @name: Line name +* @hog: Pointer to the device node that hogs this line (if any) +* @debounce_period_us: Debounce period in microseconds +* +* These are obtained using gpiod_get() and are preferable to the old +* integer-based handles. +* +* Contrary to integers, a pointer to a gpio_desc is guaranteed to be valid
&struct gpio_desc
Quoted 30 lines
drivers/gpio/gpiolib.h +2
-0+* until the GPIO is released. +*/ struct gpio_desc {struct gpio_device *gdev;unsigned long flags;include/linux/gpio/consumer.h +0
-15@@ -8,27 +8,16 @@#include <linux/err.h> struct device ; - -/** -* Opaque descriptor for a GPIO. These are obtained using gpiod_get() and are -* preferable to the old integer-based handles. -* -* Contrary to integers, a pointer to a gpio_desc is guaranteed to be valid -* until the GPIO is released. -*/ struct gpio_desc ; - -/** -* Opaque descriptor for a structure of GPIO array attributes. This structure -* is attached to struct gpiod_descs obtained from gpiod_get_array() and can be -* passed back to get/set array functions in order to activate fast processing -* path if applicable. -*/ struct gpio_array ;
include/linux/gpio/consumer.h line 20
Quoted 10 lines
include/linux/gpio/consumer.h +6
-2/** -* Struct containing an array of descriptors that can be obtained using -* gpiod_get_array(). +* struct gpio_descs - Struct containing an array of descriptors that can be +* obtained using gpiod_get_array() +* +* @info: Pointer to the opaque gpio_array structure +* @ndescs: Number of held descriptors +* desc: Array of pointers to GPIO descriptors
Missed @?
Quoted 4 lines
include/linux/gpio/consumer.h +0
-0*/ struct gpio_descs {struct gpio_array *info;
include/linux/gpio/consumer.h struct gpio_descs { · line 39
Quoted 10 lines
include/linux/gpio/consumer.h +5
-2@@ -43,8 +32,16 @@ struct gpio_descs {#define GPIOD_FLAGS_BIT_NONEXCLUSIVE BIT(4)/** -* Optional flags that can be passed to one of gpiod_* to configure direction -* and output value. These values cannot be OR'd. +* enum gpiod_flags - Optional flags that can be passed to one of gpiod_* to +* configure direction and output value. These values +* cannot be OR'd. +* +* @GPIOD_ASIS: Don't change the direction
Don't change anything
(Not only direction, also the output value. Some hardware allows to change output buffer value even if the line is configured as input).
Quoted 11 lines
include/linux/gpio/consumer.h +5
-0+* @GPIOD_IN: Set lines to input mode +* @GPIOD_OUT_LOW: Set lines to output and drive them low +* @GPIOD_OUT_HIGH: Set lines to output and drive them high +* @GPIOD_OUT_LOW_OPEN_DRAIN: Set lines to open-drain output and drive them low +* @GPIOD_OUT_HIGH_OPEN_DRAIN: Set lines to open-drain output and drive them high */ enum gpiod_flags {GPIOD_ASIS =0 ,Signature · 1 line
2.30.1
Signature · 2 lines
With Best Regards, Andy Shevchenko
Quoted 26 lines · Andy Shevchenko
Quoted 4 lines · Bartosz Golaszewski
We have several comments that start with '/**' but don't conform to the kernel doc standard. Add proper detailed descriptions for the affected definitions and move the docs from the forward declarations to the struct definitions where applicable.
Reviewed-by Andy Shevchenko <[email protected]>A few comments below.
Quoted 15 lines
Reported-by Randy Dunlap <[email protected]>Signed-off-by Bartosz Golaszewski <[email protected]>--- drivers/gpio/gpiolib.h | 31 +++++++++++++++++++++++++++++++ include/linux/gpio/consumer.h | 35 ++++++++++++++++------------------- 2 files changed, 47 insertions(+), 19 deletions(-)drivers/gpio/gpiolib.h +0
-0@@ -72,6 +72,20 @@ struct gpio_device {/* gpio suffixes used for ACPI and device tree lookup */ static __maybe_unused const char *const gpio_suffixes[] = {"gpios" ,"gpio" };
Quoted 6 lines
drivers/gpio/gpiolib.h struct gpio_device { · line 77
Quoted 4 lines
drivers/gpio/gpiolib.h +3
-0+/** +* struct gpio_array - Opaque descriptor for a structure of GPIO array attributes +* I dunno we need these blank lines.
I think it looks better. Some docs use it some don't, there's no standard.
Quoted 122 lines
drivers/gpio/gpiolib.h struct gpio_device { · line 79
Quoted 3 lines
drivers/gpio/gpiolib.h +2
-0+* @desc: Array of pointers to the GPIO descriptors +* @size: Number of elements in desc in @desc
or
in the array of the descriptor pointers
drivers/gpio/gpiolib.h struct gpio_device { · line 83
Quoted 4 lines
drivers/gpio/gpiolib.h +4
-0+* @chip: Parent GPIO chip +* @get_mask: Get mask used in fastpath. +* @set_mask: Set mask used in fastpath. +* @invert_mask: Invert mask used in fastpath. Why some of the descriptions are with grammar period and some w/o?
Quoted 17 lines
drivers/gpio/gpiolib.h +5
-0+* +* This structure is attached to struct gpiod_descs obtained from +* gpiod_get_array() and can be passed back to get/set array functions in order +* to activate fast processing path if applicable. +*/ struct gpio_array {struct gpio_desc **desc;unsigned int size;drivers/gpio/gpiolib.h +5
-0@@ -96,6 +110,23 @@ int gpiod_set_array_value_complex(bool raw, bool can_sleep,extern spinlock_t gpio_lock;extern struct list_head gpio_devices; + +/** +* struct gpio_desc - Opaque descriptor for a GPIO +* +* @gdev: Pointer to the parent GPIO device drivers/gpio/gpiolib.h int gpiod_set_array_value_complex(bool raw, bool can_sleep, · line 127
Quoted 10 lines
drivers/gpio/gpiolib.h +10
-0+* @flags: Binary descriptor flags +* @label: Name of the consumer +* @name: Line name +* @hog: Pointer to the device node that hogs this line (if any) +* @debounce_period_us: Debounce period in microseconds +* +* These are obtained using gpiod_get() and are preferable to the old +* integer-based handles. +* +* Contrary to integers, a pointer to a gpio_desc is guaranteed to be valid &struct
gpio_descQuoted 30 lines
drivers/gpio/gpiolib.h +2
-0+* until the GPIO is released. +*/ struct gpio_desc {struct gpio_device *gdev;unsigned long flags;include/linux/gpio/consumer.h +0
-15@@ -8,27 +8,16 @@#include <linux/err.h> struct device ; - -/** -* Opaque descriptor for a GPIO. These are obtained using gpiod_get() and are -* preferable to the old integer-based handles. -* -* Contrary to integers, a pointer to a gpio_desc is guaranteed to be valid -* until the GPIO is released. -*/ struct gpio_desc ; - -/** -* Opaque descriptor for a structure of GPIO array attributes. This structure -* is attached to struct gpiod_descs obtained from gpiod_get_array() and can be -* passed back to get/set array functions in order to activate fast processing -* path if applicable. -*/ struct gpio_array ;include/linux/gpio/consumer.h line 20
Quoted 10 lines
include/linux/gpio/consumer.h +6
-2/** -* Struct containing an array of descriptors that can be obtained using -* gpiod_get_array(). +* struct gpio_descs - Struct containing an array of descriptors that can be +* obtained using gpiod_get_array() +* +* @info: Pointer to the opaque gpio_array structure +* @ndescs: Number of held descriptors +* desc: Array of pointers to GPIO descriptors Missed @?
Quoted 4 lines
include/linux/gpio/consumer.h +0
-0*/ struct gpio_descs {struct gpio_array *info;include/linux/gpio/consumer.h struct gpio_descs { · line 39
Quoted 10 lines
include/linux/gpio/consumer.h +5
-2@@ -43,8 +32,16 @@ struct gpio_descs {#define GPIOD_FLAGS_BIT_NONEXCLUSIVE BIT(4)/** -* Optional flags that can be passed to one of gpiod_* to configure direction -* and output value. These values cannot be OR'd. +* enum gpiod_flags - Optional flags that can be passed to one of gpiod_* to +* configure direction and output value. These values +* cannot be OR'd. +* +* @GPIOD_ASIS: Don't change the direction Don't change anything
(Not only direction, also the output value. Some hardware allows to change output buffer value even if the line is configured as input).
Quoted 11 lines
include/linux/gpio/consumer.h +5
-1+* @GPIOD_IN: Set lines to input mode +* @GPIOD_OUT_LOW: Set lines to output and drive them low +* @GPIOD_OUT_HIGH: Set lines to output and drive them high +* @GPIOD_OUT_LOW_OPEN_DRAIN: Set lines to open-drain output and drive them low +* @GPIOD_OUT_HIGH_OPEN_DRAIN: Set lines to open-drain output and drive them high */ enum gpiod_flags {GPIOD_ASIS =0 , --2.30.1
Quoted 5 lines
--
With Best Regards,
Andy Shevchenko
Fixed the rest. Thanks!
Bart
Quoted 24 lines · Bartosz Golaszewski
We have several comments that start with '/**' but don't conform to the kernel doc standard. Add proper detailed descriptions for the affected definitions and move the docs from the forward declarations to the struct definitions where applicable.
Reported-by Randy Dunlap <[email protected]>Signed-off-by Bartosz Golaszewski <[email protected]>--- drivers/gpio/gpiolib.h | 31 +++++++++++++++++++++++++++++++ include/linux/gpio/consumer.h | 35 ++++++++++++++++------------------- 2 files changed, 47 insertions(+), 19 deletions(-)drivers/gpio/gpiolib.h +4
-0@@ -72,6 +72,20 @@ struct gpio_device {/* gpio suffixes used for ACPI and device tree lookup */ static __maybe_unused const char *const gpio_suffixes[] = {"gpios" ,"gpio" }; +/** +* struct gpio_array - Opaque descriptor for a structure of GPIO array attributes +* +* @desc: Array of pointers to the GPIO descriptors
drivers/gpio/gpiolib.h struct gpio_device { · line 88
Quoted 10 lines
drivers/gpio/gpiolib.h +10
-0+* @size: Number of elements in desc +* @chip: Parent GPIO chip +* @get_mask: Get mask used in fastpath. +* @set_mask: Set mask used in fastpath. +* @invert_mask: Invert mask used in fastpath. +* +* This structure is attached to struct gpiod_descs obtained from +* gpiod_get_array() and can be passed back to get/set array functions in order +* to activate fast processing path if applicable. +*/
scripts/kernel-doc says:
gpiolib.h:70: warning: Function parameter or member 'notifier' not described in 'gpio_device' gpiolib.h:70: warning: Function parameter or member 'pin_ranges' not described in 'gpio_device' 2 warnings
Quoted 52 lines
drivers/gpio/gpiolib.h +17
-0struct gpio_array {struct gpio_desc **desc;unsigned int size;@@ -96,6 +110,23 @@ int gpiod_set_array_value_complex(bool raw, bool can_sleep,extern spinlock_t gpio_lock;extern struct list_head gpio_devices; + +/** +* struct gpio_desc - Opaque descriptor for a GPIO +* +* @gdev: Pointer to the parent GPIO device +* @flags: Binary descriptor flags +* @label: Name of the consumer +* @name: Line name +* @hog: Pointer to the device node that hogs this line (if any) +* @debounce_period_us: Debounce period in microseconds +* +* These are obtained using gpiod_get() and are preferable to the old +* integer-based handles. +* +* Contrary to integers, a pointer to a gpio_desc is guaranteed to be valid +* until the GPIO is released. +*/ struct gpio_desc {struct gpio_device *gdev;unsigned long flags;include/linux/gpio/consumer.h +0
-15@@ -8,27 +8,16 @@#include <linux/err.h> struct device ; - -/** -* Opaque descriptor for a GPIO. These are obtained using gpiod_get() and are -* preferable to the old integer-based handles. -* -* Contrary to integers, a pointer to a gpio_desc is guaranteed to be valid -* until the GPIO is released. -*/ struct gpio_desc ; - -/** -* Opaque descriptor for a structure of GPIO array attributes. This structure -* is attached to struct gpiod_descs obtained from gpiod_get_array() and can be -* passed back to get/set array functions in order to activate fast processing -* path if applicable. -*/ struct gpio_array ;
include/linux/gpio/consumer.h line 20
Quoted 10 lines
include/linux/gpio/consumer.h +6
-2/** -* Struct containing an array of descriptors that can be obtained using -* gpiod_get_array(). +* struct gpio_descs - Struct containing an array of descriptors that can be +* obtained using gpiod_get_array() +* +* @info: Pointer to the opaque gpio_array structure +* @ndescs: Number of held descriptors +* desc: Array of pointers to GPIO descriptors
consumer.h:26: warning: Function parameter or member 'desc' not described in 'gpio_descs'
as Andy pointed out.
Several of Andy's kernel-doc notation suggestions also look good.
Quoted 22 lines
include/linux/gpio/consumer.h +10
-2*/ struct gpio_descs {struct gpio_array *info;@@ -43,8 +32,16 @@ struct gpio_descs {#define GPIOD_FLAGS_BIT_NONEXCLUSIVE BIT(4)/** -* Optional flags that can be passed to one of gpiod_* to configure direction -* and output value. These values cannot be OR'd. +* enum gpiod_flags - Optional flags that can be passed to one of gpiod_* to +* configure direction and output value. These values +* cannot be OR'd. +* +* @GPIOD_ASIS: Don't change the direction +* @GPIOD_IN: Set lines to input mode +* @GPIOD_OUT_LOW: Set lines to output and drive them low +* @GPIOD_OUT_HIGH: Set lines to output and drive them high +* @GPIOD_OUT_LOW_OPEN_DRAIN: Set lines to open-drain output and drive them low +* @GPIOD_OUT_HIGH_OPEN_DRAIN: Set lines to open-drain output and drive them high */ enum gpiod_flags {GPIOD_ASIS =0 ,
Signature · 1 line
~Randy