gpio/consumer.h: don't use "/**" for non-kernel-doc comments
PATCH 1/1 gpio/consumer.h: don't use "/**" for non-kernel-doc comments
Use "/*" to begin non-kernel-doc comments instead of "/**", which indicates the beginning of kernel-doc notation.
Quietens these kernel-doc warnings:
consumer.h:13: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* Opaque descriptor for a GPIO. These are obtained using gpiod_get() and are
consumer.h:13: warning: missing initial short description on line:
* Opaque descriptor for a GPIO. These are obtained using gpiod_get() and are
consumer.h:22: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* Opaque descriptor for a structure of GPIO array attributes. This structure
consumer.h:22: warning: missing initial short description on line:
* Opaque descriptor for a structure of GPIO array attributes. This structure
consumer.h:30: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* Struct containing an array of descriptors that can be obtained using
consumer.h:30: warning: missing initial short description on line:
* Struct containing an array of descriptors that can be obtained using
consumer.h:46: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* Optional flags that can be passed to one of gpiod_* to configure direction
consumer.h:46: warning: missing initial short description on line:
* Optional flags that can be passed to one of gpiod_* to configure direction
--- include/linux/gpio/consumer.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
include/linux/gpio/consumer.h +4 -4
@@ -9,7 +9,7 @@struct device ; -/** +/* * Opaque descriptor for a GPIO. These are obtained using gpiod_get() and are * preferable to the old integer-based handles. *
@@ -18,7 +18,7 @@ struct device;*/ 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
@@ -26,7 +26,7 @@ struct gpio_desc;*/ struct gpio_array ; -/** +/* * Struct containing an array of descriptors that can be obtained using * gpiod_get_array(). */
@@ -42,7 +42,7 @@ struct gpio_descs {#define GPIOD_FLAGS_BIT_OPEN_DRAIN BIT(3)#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. */
Quoted 22 lines · Randy Dunlap
Use "/*" to begin non-kernel-doc comments instead of "/**", which indicates the beginning of kernel-doc notation.
Quietens these kernel-doc warnings:
consumer.h:13: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer
Documentation/doc-guide/kernel-doc.rst
* Opaque descriptor for a GPIO. These are obtained usinggpiod_get()and are
consumer.h:13: warning: missing initial short description on line:
* Opaque descriptor for a GPIO. These are obtained usinggpiod_get()and are
consumer.h:22: warning: This comment starts with '/**', but isn't a kernel-doc comment. ReferDocumentation/doc-guide/kernel-doc.rst
* Opaque descriptor for a structure of GPIO array attributes. This structure
consumer.h:22: warning: missing initial short description on line:
* Opaque descriptor for a structure of GPIO array attributes. This structure
consumer.h:30: warning: This comment starts with '/**', but isn't a kernel-doc comment. ReferDocumentation/doc-guide/kernel-doc.rst
* Struct containing an array of descriptors that can be obtained using
consumer.h:30: warning: missing initial short description on line:
* Struct containing an array of descriptors that can be obtained using
consumer.h:46: warning: This comment starts with '/**', but isn't a kernel-doc comment. ReferDocumentation/doc-guide/kernel-doc.rst
* Optional flags that can be passed to one of gpiod_* to configure direction
consumer.h:46: warning: missing initial short description on line:
* Optional flags that can be passed to one of gpiod_* to configure direction
Quoted 4 lines
Signed-off-by Randy Dunlap <[email protected]>Cc Linus Walleij <[email protected]>Cc Bartosz Golaszewski <[email protected]>
In this case the ambition was to provide proper kerneldoc for sure.
Is it possible to just fix the documentation?
Yours,
Linus Walleij
Quoted 24 lines · Linus Walleij
Quoted 22 lines · Randy Dunlap
Use "/*" to begin non-kernel-doc comments instead of "/**", which indicates the beginning of kernel-doc notation.
Quietens these kernel-doc warnings:
consumer.h:13: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer
Documentation/doc-guide/kernel-doc.rst
* Opaque descriptor for a GPIO. These are obtained usinggpiod_get()and are
consumer.h:13: warning: missing initial short description on line:
* Opaque descriptor for a GPIO. These are obtained usinggpiod_get()and are
consumer.h:22: warning: This comment starts with '/**', but isn't a kernel-doc comment. ReferDocumentation/doc-guide/kernel-doc.rst
* Opaque descriptor for a structure of GPIO array attributes. This structure
consumer.h:22: warning: missing initial short description on line:
* Opaque descriptor for a structure of GPIO array attributes. This structure
consumer.h:30: warning: This comment starts with '/**', but isn't a kernel-doc comment. ReferDocumentation/doc-guide/kernel-doc.rst
* Struct containing an array of descriptors that can be obtained using
consumer.h:30: warning: missing initial short description on line:
* Struct containing an array of descriptors that can be obtained using
consumer.h:46: warning: This comment starts with '/**', but isn't a kernel-doc comment. ReferDocumentation/doc-guide/kernel-doc.rst
* Optional flags that can be passed to one of gpiod_* to configure direction
consumer.h:46: warning: missing initial short description on line:
* Optional flags that can be passed to one of gpiod_* to configure direction
Quoted 6 lines
Quoted 4 lines
Signed-off-by Randy Dunlap <[email protected]>Cc Linus Walleij <[email protected]>Cc Bartosz Golaszewski <[email protected]>In this case the ambition was to provide proper kerneldoc for sure.
Well, the 2 opaque warnings (lines 13 and 22) are just bare "struct gpio_zzz;", so kernel-doc wouldn't be appropriate there. Those structs are in drivers/gpio/gpiolib.h (for anyone else who is reading along) -- and not documented there either.
For the other 2 /** warnings, I don't think that I am the right person to add kernel-doc info for them...
Quoted 1 line
Is it possible to just fix the documentation?
or just ignore this patch.
Signature · 1 line
~Randy