* [PATCH] gpio/consumer.h: don't use "/**" for non-kernel-doc comments
@ 2022-01-30 7:31 Randy Dunlap
2022-01-31 11:24 ` Linus Walleij
0 siblings, 1 reply; 3+ messages in thread
From: Randy Dunlap @ 2022-01-30 7:31 UTC (permalink / raw)
To: linux-kernel; +Cc: Randy Dunlap, Linus Walleij, Bartosz Golaszewski, linux-gpio
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
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Linus Walleij <linus.walleij@linaro.org>
Cc: Bartosz Golaszewski <brgl@bgdev.pl>
Cc: linux-gpio@vger.kernel.org
---
include/linux/gpio/consumer.h | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
--- linux-next-20220128.orig/include/linux/gpio/consumer.h
+++ linux-next-20220128/include/linux/gpio/consumer.h
@@ -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.
*/
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH] gpio/consumer.h: don't use "/**" for non-kernel-doc comments
2022-01-30 7:31 [PATCH] gpio/consumer.h: don't use "/**" for non-kernel-doc comments Randy Dunlap
@ 2022-01-31 11:24 ` Linus Walleij
2022-02-01 3:52 ` Randy Dunlap
0 siblings, 1 reply; 3+ messages in thread
From: Linus Walleij @ 2022-01-31 11:24 UTC (permalink / raw)
To: Randy Dunlap; +Cc: linux-kernel, Bartosz Golaszewski, linux-gpio
On Sun, Jan 30, 2022 at 8:31 AM Randy Dunlap <rdunlap@infradead.org> wrote:
> 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
>
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Linus Walleij <linus.walleij@linaro.org>
> Cc: Bartosz Golaszewski <brgl@bgdev.pl>
> Cc: linux-gpio@vger.kernel.org
In this case the ambition was to provide proper kerneldoc for sure.
Is it possible to just fix the documentation?
Yours,
Linus Walleij
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH] gpio/consumer.h: don't use "/**" for non-kernel-doc comments
2022-01-31 11:24 ` Linus Walleij
@ 2022-02-01 3:52 ` Randy Dunlap
0 siblings, 0 replies; 3+ messages in thread
From: Randy Dunlap @ 2022-02-01 3:52 UTC (permalink / raw)
To: Linus Walleij; +Cc: linux-kernel, Bartosz Golaszewski, linux-gpio
On 1/31/22 03:24, Linus Walleij wrote:
> On Sun, Jan 30, 2022 at 8:31 AM Randy Dunlap <rdunlap@infradead.org> wrote:
>
>> 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
>>
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>> Cc: Linus Walleij <linus.walleij@linaro.org>
>> Cc: Bartosz Golaszewski <brgl@bgdev.pl>
>> Cc: linux-gpio@vger.kernel.org
>
> 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...
> Is it possible to just fix the documentation?
or just ignore this patch.
--
~Randy
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2022-02-01 3:52 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-01-30 7:31 [PATCH] gpio/consumer.h: don't use "/**" for non-kernel-doc comments Randy Dunlap
2022-01-31 11:24 ` Linus Walleij
2022-02-01 3:52 ` Randy Dunlap
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).