gpiolib: Update the kernel documentation - add Return sections
PATCH v3 1/1 gpiolib: Update the kernel documentation - add Return sections
$ scripts/kernel-doc -v -none -Wall drivers/gpio/gpiolib* 2>&1 | grep -w warning | wc -l 67
Fix these by adding Return sections. While at it, make sure all of Return sections use the same style.
Signed-off-by Andy Shevchenko <[email protected]>
Reviewed-by Randy Dunlap <[email protected]>
Tested-by Randy Dunlap <[email protected]>
Signed-off-by Andy Shevchenko <[email protected]>
---
v3: consistently used %FOO for constants, "active-low" and "errno" (Bart)
drivers/gpio/gpiolib-acpi.c | 22 +++-- drivers/gpio/gpiolib-cdev.c | 8 +- drivers/gpio/gpiolib-devres.c | 38 +++++++- drivers/gpio/gpiolib-legacy.c | 3 + drivers/gpio/gpiolib-of.c | 48 ++++++++--- drivers/gpio/gpiolib-swnode.c | 2 +- drivers/gpio/gpiolib-sysfs.c | 6 +- drivers/gpio/gpiolib.c | 157 +++++++++++++++++++++++++++------- 8 files changed, 226 insertions(+), 58 deletions(-)
drivers/gpio/gpiolib-acpi.c +17 -5
@@ -153,8 +153,12 @@ static int acpi_gpiochip_find(struct gpio_chip *gc, const void *data)* @path: ACPI GPIO controller full path name, (e.g. "\\_SB.GPO1") * @pin: ACPI GPIO pin number (0-based, controller-relative) * -* Return: GPIO descriptor to use with Linux generic GPIO API, or ERR_PTR -* error value. Specifically returns %-EPROBE_DEFER if the referenced GPIO +* Returns: +* GPIO descriptor to use with Linux generic GPIO API. +* If the GPIO cannot be translated or there is an error an ERR_PTR is +* returned. +* +* Specifically returns %-EPROBE_DEFER if the referenced GPIO * controller does not have GPIO chip registered at the moment. This is to * support probe deferral. */
@@ -224,6 +228,9 @@ EXPORT_SYMBOL_GPL(acpi_gpio_get_irq_resource);* I/O resource or return False if not. * @ares: Pointer to the ACPI resource to fetch * @agpio: Pointer to a &struct acpi_resource_gpio to store the output pointer +* +* Returns: +* %true if GpioIo resource is found, %false otherwise. */ bool acpi_gpio_get_io_resource (struct acpi_resource *ares,struct acpi_resource_gpio **agpio)
@@ -876,7 +883,9 @@ static int acpi_gpio_property_lookup(struct fwnode_handle *fwnode,* that case @index is used to select the GPIO entry in the property value * (in case of multiple). * -* If the GPIO cannot be translated or there is an error, an ERR_PTR is +* Returns: +* GPIO descriptor to use with Linux generic GPIO API. +* If the GPIO cannot be translated or there is an error an ERR_PTR is * returned. * * Note: if the GPIO resource has multiple entries in the pin list, this
@@ -924,6 +933,8 @@ static struct gpio_desc *acpi_get_gpiod_by_index(struct acpi_device *adev,* resource with the relevant information from a data-only ACPI firmware node * and uses that to obtain the GPIO descriptor to return. * +* Returns: +* GPIO descriptor to use with Linux generic GPIO API. * If the GPIO cannot be translated or there is an error an ERR_PTR is * returned. */
@@ -1042,7 +1053,8 @@ struct gpio_desc *acpi_find_gpio(struct fwnode_handle *fwnode,* The GPIO is considered wake capable if the GpioInt resource specifies * SharedAndWake or ExclusiveAndWake. * -* Return: Linux IRQ number (> %0) on success, negative errno on failure. +* Returns: +* Linux IRQ number (> 0) on success, negative errno on failure. */ int acpi_dev_gpio_irq_wake_get_by (struct acpi_device *adev,const char *con_id,int index,bool *wake_capable)
@@ -1429,7 +1441,7 @@ static int acpi_find_gpio_count(struct acpi_resource *ares, void *data)* @fwnode: firmware node of the GPIO consumer * @con_id: function within the GPIO consumer * -* Return: +* Returns: * The number of GPIOs associated with a firmware node / function or %-ENOENT, * if no GPIO has been assigned to the requested function. */
drivers/gpio/gpiolib-cdev.c +6 -2
@@ -2748,7 +2748,9 @@ static ssize_t lineinfo_watch_read(struct file *file, char __user *buf,* gpio_chrdev_open() - open the chardev for ioctl operations * @inode: inode for this chardev * @file: file struct for storing private data -* Returns 0 on success +* +* Returns: +* 0 on success, or negative errno on failure. */ static int gpio_chrdev_open (struct inode *inode,struct file *file) {
@@ -2814,7 +2816,9 @@ static int gpio_chrdev_open(struct inode *inode, struct file *file)* gpio_chrdev_release() - close chardev after ioctl operations * @inode: inode for this chardev * @file: file struct for storing private data -* Returns 0 on success +* +* Returns: +* 0 on success, or negative errno on failure. */ static int gpio_chrdev_release (struct inode *inode,struct file *file) {
drivers/gpio/gpiolib-devres.c +36 -2
@@ -52,6 +52,11 @@ static int devm_gpiod_match_array(struct device *dev, void *res, void *data)* Managed gpiod_get(). GPIO descriptors returned from this function are * automatically disposed on driver detach. See gpiod_get() for detailed * information about behavior and return values. +* +* Returns: +* The GPIO descriptor corresponding to the function @con_id of device +* dev, %-ENOENT if no GPIO has been assigned to the requested function, or +* another IS_ERR() code if an error occurred while trying to acquire the GPIO. */ struct gpio_desc *__must_check devm_gpiod_get(struct device *dev, const char *con_id,
@@ -70,6 +75,11 @@ EXPORT_SYMBOL_GPL(devm_gpiod_get);* Managed gpiod_get_optional(). GPIO descriptors returned from this function * are automatically disposed on driver detach. See gpiod_get_optional() for * detailed information about behavior and return values. +* +* Returns: +* The GPIO descriptor corresponding to the function @con_id of device +* dev, NULL if no GPIO has been assigned to the requested function, or +* another IS_ERR() code if an error occurred while trying to acquire the GPIO. */ struct gpio_desc *__must_check devm_gpiod_get_optional(struct device *dev, const char *con_id,
@@ -89,6 +99,11 @@ EXPORT_SYMBOL_GPL(devm_gpiod_get_optional);* Managed gpiod_get_index(). GPIO descriptors returned from this function are * automatically disposed on driver detach. See gpiod_get_index() for detailed * information about behavior and return values. +* +* Returns: +* The GPIO descriptor corresponding to the function @con_id of device +* dev, %-ENOENT if no GPIO has been assigned to the requested function, or +* another IS_ERR() code if an error occurred while trying to acquire the GPIO. */ struct gpio_desc *__must_check devm_gpiod_get_index(struct device *dev, const char *con_id,
@@ -141,8 +156,10 @@ EXPORT_SYMBOL_GPL(devm_gpiod_get_index);* GPIO descriptors returned from this function are automatically disposed on * driver detach. * -* On successful request the GPIO pin is configured in accordance with -* provided @flags. +* Returns: +* The GPIO descriptor corresponding to the function @con_id of device +* dev, %-ENOENT if no GPIO has been assigned to the requested function, or +* another IS_ERR() code if an error occurred while trying to acquire the GPIO. */ struct gpio_desc *devm_fwnode_gpiod_get_index(struct device *dev, struct fwnode_handle *fwnode,
@@ -182,6 +199,11 @@ EXPORT_SYMBOL_GPL(devm_fwnode_gpiod_get_index);* function are automatically disposed on driver detach. See * gpiod_get_index_optional() for detailed information about behavior and * return values. +* +* Returns: +* The GPIO descriptor corresponding to the function @con_id of device +* dev, %NULL if no GPIO has been assigned to the requested function, or +* another IS_ERR() code if an error occurred while trying to acquire the GPIO. */ struct gpio_desc *__must_check devm_gpiod_get_index_optional(struct device *dev, const char *con_id,
@@ -207,6 +229,12 @@ EXPORT_SYMBOL_GPL(devm_gpiod_get_index_optional);* Managed gpiod_get_array(). GPIO descriptors returned from this function are * automatically disposed on driver detach. See gpiod_get_array() for detailed * information about behavior and return values. +* +* Returns: +* The GPIO descriptors corresponding to the function @con_id of device +* dev, %-ENOENT if no GPIO has been assigned to the requested function, +* or another IS_ERR() code if an error occurred while trying to acquire +* the GPIOs. */ struct gpio_descs *__must_check devm_gpiod_get_array(struct device *dev, const char *con_id,
@@ -243,6 +271,12 @@ EXPORT_SYMBOL_GPL(devm_gpiod_get_array);* function are automatically disposed on driver detach. * See gpiod_get_array_optional() for detailed information about behavior and * return values. +* +* Returns: +* The GPIO descriptors corresponding to the function @con_id of device +* dev, %NULL if no GPIO has been assigned to the requested function, +* or another IS_ERR() code if an error occurred while trying to acquire +* the GPIOs. */ struct gpio_descs *__must_check devm_gpiod_get_array_optional(struct device *dev, const char *con_id,
drivers/gpio/gpiolib-legacy.c +3 -0
@@ -22,6 +22,9 @@ EXPORT_SYMBOL_GPL(gpio_free);* @label: a literal description string of this GPIO * * **DEPRECATED** This function is deprecated and must not be used in new code. +* +* Returns: +* 0 on success, or negative errno on failure. */ int gpio_request_one (unsigned gpio,unsigned long flags,const char *label) {
drivers/gpio/gpiolib-of.c +34 -14
103 lines not on this page · raw message
drivers/gpio/gpiolib-swnode.c +1 -1
@@ -106,7 +106,7 @@ struct gpio_desc *swnode_find_gpio(struct fwnode_handle *fwnode,* system-global GPIOs * @con_id: function within the GPIO consumer * -* Return: +* Returns: * The number of GPIOs associated with a device / function or %-ENOENT, * if no GPIO has been assigned to the requested function. */
drivers/gpio/gpiolib-sysfs.c +4 -2
@@ -568,7 +568,8 @@ static struct class gpio_class = {* will see "direction" sysfs attribute which may be used to change * the gpio's direction. A "value" attribute will always be provided. * -* Returns zero on success, else an error. +* Returns: +* 0 on success, or negative errno on failure. */ int gpiod_export (struct gpio_desc *desc,bool direction_may_change) {
@@ -667,7 +668,8 @@ static int match_export(struct device *dev, const void *desc)* Set up a symlink from /sys/.../dev/name to /sys/class/gpio/gpioN * node. Caller is responsible for unlinking. * -* Returns zero on success, else an error. +* Returns: +* 0 on success, or negative errno on failure. */ int gpiod_export_link (struct device *dev,const char *name,struct gpio_desc *desc)
drivers/gpio/gpiolib.c +125 -32
431 lines not on this page · raw message
Signature · 1 line
2.43.0.rc1.1336.g36b5255a03ac
Bartosz Golaszewski
AppliedFrom: Bartosz Golaszewski <[email protected]>
Quoted 8 lines · Andy Shevchenko
$ scripts/kernel-doc -v -none -Wall drivers/gpio/gpiolib* 2>&1 | grep -w warning | wc -l 67Fix these by adding Return sections. While at it, make sure all of Return sections use the same style.
[...]
Applied, thanks!
[1/1] gpiolib: Update the kernel documentation - add Return sections
commit: b3b12a60eec1415ac68e79e3e6f932772765a897
Best regards,
Signature · 1 line
Bartosz Golaszewski <[email protected]>