Skip to contentSkip to conversation

gpiolib: Update the kernel documentation - add Return sections

PATCH Superseded Andy Shevchenko 3 participants 8 messages Apr 4, 2024 – Apr 8, 2024

Subsystems (3)

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

PATCH 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.

---
 drivers/gpio/gpiolib-acpi.c   |  22 +++--
 drivers/gpio/gpiolib-cdev.c   |   8 +-
 drivers/gpio/gpiolib-devres.c |  44 +++++++++-
 drivers/gpio/gpiolib-legacy.c |   3 +
 drivers/gpio/gpiolib-of.c     |  48 ++++++++---
 drivers/gpio/gpiolib-swnode.c |   4 +-
 drivers/gpio/gpiolib-sysfs.c  |   6 +-
 drivers/gpio/gpiolib.c        | 157 +++++++++++++++++++++++++++-------
 8 files changed, 233 insertions(+), 59 deletions(-)
drivers/gpio/gpiolib-acpi.c +17 -5
index 7f140df40f35..9aac44f0816d 100644
@@ -136,8 +136,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.
  */
@@ -207,6 +211,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)
@@ -859,7 +866,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
@@ -910,6 +919,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.
  */
@@ -1023,7 +1034,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 *name, int index,
 				  bool *wake_capable)
@@ -1406,7 +1418,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
index fa9635610251..4cd0d5009406 100644
@@ -2710,7 +2710,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)
 {
@@ -2776,7 +2778,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 +42 -2

98 lines not on this page · raw message

drivers/gpio/gpiolib-legacy.c +3 -0
index 5a9911ae9125..d27142418f9f 100644
@@ -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 +2 -2
index fa52bdb1a29a..7298f1247dd3 100644
@@ -96,8 +96,8 @@ struct gpio_desc *swnode_find_gpio(struct fwnode_handle *fwnode,
  *		system-global GPIOs
  * @con_id:	function within the GPIO consumer
  *
- * Return:
- * The number of GPIOs associated with a device / function or %-ENOENT,
+ * Returns:
+ * The number of GPIOs associated with a device / function or -ENOENT,
  * if no GPIO has been assigned to the requested function.
  */
 int swnode_gpio_count(const struct fwnode_handle *fwnode, const char *con_id)
drivers/gpio/gpiolib-sysfs.c +4 -2
index 26202586fd39..17ed229412af 100644
@@ -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.1.gbec44491f096
Reviewed-by Tested-by on v1 1/1
#1 lore raw

Hi,

Quoted 7 lines · Andy Shevchenko
$ 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.

Quoted 10 lines
---
 drivers/gpio/gpiolib-acpi.c   |  22 +++--
 drivers/gpio/gpiolib-cdev.c   |   8 +-
 drivers/gpio/gpiolib-devres.c |  44 +++++++++-
 drivers/gpio/gpiolib-legacy.c |   3 +
 drivers/gpio/gpiolib-of.c     |  48 ++++++++---
 drivers/gpio/gpiolib-swnode.c |   4 +-
 drivers/gpio/gpiolib-sysfs.c  |   6 +-
 drivers/gpio/gpiolib.c        | 157 +++++++++++++++++++++++++++-------
 8 files changed, 233 insertions(+), 59 deletions(-)

I would use %true, %false, %NULL, %0, and %1 in a few places.

s/error-code/error code/
or
s/error-code/errno/

I would s/active-low/active low/

or it can just be merged as is. It's a nice improvement.

Thanks.

Signature · 1 line
#Randy
#2 lore raw
Quoted 2 lines · Randy Dunlap

I would s/active-low/active low/

Active-low is the correct jargon in this case.

regards,
dan carpenter

#3 lore raw
In reply to Randy Dunlap
Quoted 6 lines · Randy Dunlap
Quoted 5 lines · Andy Shevchenko
$ 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.

...

Quoted 1 line

I would use %true, %false, %NULL, %0, and %1 in a few places.

Why? I specifically removed % from all of them, it's not so useful. Do we have, btw, generated HTML with these % as an example to see the difference. Maybe that helps to understand this better?

Quoted 7 lines

s/error-code/error code/
or
s/error-code/errno/

I would s/active-low/active low/

or it can just be merged as is. It's a nice improvement.

That's what I prefer as any of your comments may touch other parts of the documentation and need to be aligned across all comments, which is out scope of this patch.

Quoted 2 lines

Thank you!

Signature · 2 lines
With Best Regards,
Andy Shevchenko
#4 lore raw

Hi,

Quoted 8 lines · Andy Shevchenko
Quoted 6 lines · Randy Dunlap
Quoted 5 lines · Andy Shevchenko
$ 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.

Quoted 8 lines

...

Quoted 1 line

I would use %true, %false, %NULL, %0, and %1 in a few places.

Why? I specifically removed % from all of them, it's not so useful. Do we have, btw, generated HTML with these % as an example to see the difference. Maybe that helps to understand this better?

The leading '%' just changes the font style of constants. I don't know of any HTML that compares them.

Quoted 11 lines
Quoted 7 lines

s/error-code/error code/
or
s/error-code/errno/

I would s/active-low/active low/

or it can just be merged as is. It's a nice improvement.

That's what I prefer as any of your comments may touch other parts of the documentation and need to be aligned across all comments, which is out scope of this patch.

My comments just refer to your patched lines.

Quoted 6 lines
Quoted 3 lines

Thank you!

Signature · 1 line
#Randy
#5 lore raw
Quoted 8 lines · Randy Dunlap
Quoted 7 lines · Andy Shevchenko
Quoted 6 lines · Randy Dunlap
Quoted 5 lines · Andy Shevchenko
$ 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.

...

Quoted 8 lines
Quoted 5 lines
Quoted 1 line

I would use %true, %false, %NULL, %0, and %1 in a few places.

Why? I specifically removed % from all of them, it's not so useful. Do we have, btw, generated HTML with these % as an example to see the difference. Maybe that helps to understand this better?

The leading '%' just changes the font style of constants. I don't know of any HTML that compares them.

I meant to compare the (HTML) render to see the difference, but you already explained that it adds/modifies <font> tag or so.

Signature · 2 lines
With Best Regards,
Andy Shevchenko
#6 lore raw
In reply to Andy Shevchenko
Quoted 5 lines · Andy Shevchenko
$ 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.

Bart, this is the biggest part from the v1, I would like to have that applied first if no objections since it fixes kernel doc warnings. What do you think?

Signature · 2 lines
With Best Regards,
Andy Shevchenko
#7 lore raw
Quoted 9 lines · Andy Shevchenko
Quoted 5 lines · Andy Shevchenko
$ 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.

Bart, this is the biggest part from the v1, I would like to have that applied first if no objections since it fixes kernel doc warnings. What do you think?

Hold on a sec, I found bigger issue that needs to be backported and this patch needs to be rebased on top of it. I'll send an update.

Signature · 2 lines
With Best Regards,
Andy Shevchenko