| Message ID | 20201005070329.21055-1-warthog618@gmail.com |
|---|---|
| Headers | show |
| Series | gpio: uapi: documentation improvements | expand |
On Mon, Oct 5, 2020 at 10:07 AM Kent Gibson <warthog618@gmail.com> wrote: > > Clarify that a char array containing a string is considered 'empty' if > the first character is the null terminator. The remaining characters > are not relevant to this determination. > * @label: a functional name for this GPIO chip, such as a product > - * number, may be empty > + * number, may be empty (i.e. label[0] == '\0') I would rather put it like "...may be empty string (i.e. label == "")" And so on for the rest.
On Mon, Oct 5, 2020 at 10:04 AM Kent Gibson <warthog618@gmail.com> wrote: > > I'm intending to add some GPIO chardev documentation to > Documentation/admin-guide/gpio/chardev.rst (or perhaps > Documentation/userspace-api/??), but that is taking longer than I'd like, > so in the meantime here is a collection of minor documentation tidy-ups > and improvements to the kernel-doc that I've made along the way. > Hopefully nothing controversial - mainly formatting improvements, > and a couple of minor wording changes. Thanks. For patches 1-4 Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com> Patch 5 as well in case you agree with my comments and goind > > Cheers, > Kent. > > Kent Gibson (5): > gpio: uapi: fix kernel-doc warnings > gpio: uapi: comment consistency > gpio: uapi: kernel-doc formatting improvements > gpio: uapi: remove whitespace > gpio: uapi: clarify the meaning of 'empty' char arrays > > include/uapi/linux/gpio.h | 106 +++++++++++++++++++------------------- > 1 file changed, 54 insertions(+), 52 deletions(-) > > > base-commit: 237d96164f2c2b33d0d5094192eb743e9e1b04ad > -- > 2.28.0 >
On Mon, Oct 5, 2020 at 2:02 PM Andy Shevchenko <andy.shevchenko@gmail.com> wrote: > On Mon, Oct 5, 2020 at 10:04 AM Kent Gibson <warthog618@gmail.com> wrote: > Patch 5 as well in case you agree with my comments and goind and going to address them.
On Mon, Oct 05, 2020 at 02:01:22PM +0300, Andy Shevchenko wrote: > On Mon, Oct 5, 2020 at 10:07 AM Kent Gibson <warthog618@gmail.com> wrote: > > > > Clarify that a char array containing a string is considered 'empty' if > > the first character is the null terminator. The remaining characters > > are not relevant to this determination. > > > * @label: a functional name for this GPIO chip, such as a product > > - * number, may be empty > > + * number, may be empty (i.e. label[0] == '\0') > > I would rather put it like > "...may be empty string (i.e. label == "")" > I'm not keen on that alternative as what it suggests is actually a pointer comparison, and even if the user realizes that they may instead use "strlen(label) == 0", when they shouldn't be assuming that a null terminator is present in the array. I avoided mentioning "string" and kept it in terms of the char array for the same reason. Cheers, Kent.
On Mon, Oct 5, 2020 at 9:03 AM Kent Gibson <warthog618@gmail.com> wrote: > > I'm intending to add some GPIO chardev documentation to > Documentation/admin-guide/gpio/chardev.rst (or perhaps > Documentation/userspace-api/??), but that is taking longer than I'd like, > so in the meantime here is a collection of minor documentation tidy-ups > and improvements to the kernel-doc that I've made along the way. > Hopefully nothing controversial - mainly formatting improvements, > and a couple of minor wording changes. > > Cheers, > Kent. > > Kent Gibson (5): > gpio: uapi: fix kernel-doc warnings > gpio: uapi: comment consistency > gpio: uapi: kernel-doc formatting improvements > gpio: uapi: remove whitespace > gpio: uapi: clarify the meaning of 'empty' char arrays > > include/uapi/linux/gpio.h | 106 +++++++++++++++++++------------------- > 1 file changed, 54 insertions(+), 52 deletions(-) > > > base-commit: 237d96164f2c2b33d0d5094192eb743e9e1b04ad > -- > 2.28.0 > For the entire series: Reviewed-by: Bartosz Golaszewski <bgolaszewski@baylibre.com> Linus: can you take them for v5.10 through your tree directly? Bartosz
On Thu, Oct 8, 2020 at 5:46 PM Bartosz Golaszewski <bgolaszewski@baylibre.com> wrote: > On Mon, Oct 5, 2020 at 9:03 AM Kent Gibson <warthog618@gmail.com> wrote: > > > > I'm intending to add some GPIO chardev documentation to > > Documentation/admin-guide/gpio/chardev.rst (or perhaps > > Documentation/userspace-api/??), but that is taking longer than I'd like, > > so in the meantime here is a collection of minor documentation tidy-ups > > and improvements to the kernel-doc that I've made along the way. > > Hopefully nothing controversial - mainly formatting improvements, > > and a couple of minor wording changes. > For the entire series: > > Reviewed-by: Bartosz Golaszewski <bgolaszewski@baylibre.com> > > Linus: can you take them for v5.10 through your tree directly? I am waiting for Kent to respin them addressing Andy's comments on patch 5/5 then they can go in as fixes I think. Yours, Linus Walleij
On Tue, Oct 13, 2020 at 03:21:47PM +0200, Linus Walleij wrote: > On Thu, Oct 8, 2020 at 5:46 PM Bartosz Golaszewski > <bgolaszewski@baylibre.com> wrote: > > On Mon, Oct 5, 2020 at 9:03 AM Kent Gibson <warthog618@gmail.com> wrote: > > > > > > I'm intending to add some GPIO chardev documentation to > > > Documentation/admin-guide/gpio/chardev.rst (or perhaps > > > Documentation/userspace-api/??), but that is taking longer than I'd like, > > > so in the meantime here is a collection of minor documentation tidy-ups > > > and improvements to the kernel-doc that I've made along the way. > > > Hopefully nothing controversial - mainly formatting improvements, > > > and a couple of minor wording changes. > > > For the entire series: > > > > Reviewed-by: Bartosz Golaszewski <bgolaszewski@baylibre.com> > > > > Linus: can you take them for v5.10 through your tree directly? > > I am waiting for Kent to respin them addressing Andy's comments > on patch 5/5 then they can go in as fixes I think. > I had replied to Andy's comments - I'm prefer with my version than his suggestion: "I'm not keen on that alternative as what it suggests is actually a pointer comparison, and even if the user realizes that they may instead use "strlen(label) == 0", when they shouldn't be assuming that a null terminator is present in the array. I avoided mentioning "string" and kept it in terms of the char array for the same reason." Cheers, Kent.
On Tue, Oct 13, 2020 at 7:34 PM Kent Gibson <warthog618@gmail.com> wrote: > On Tue, Oct 13, 2020 at 03:21:47PM +0200, Linus Walleij wrote: > > On Thu, Oct 8, 2020 at 5:46 PM Bartosz Golaszewski > > <bgolaszewski@baylibre.com> wrote: ... > > I am waiting for Kent to respin them addressing Andy's comments > > on patch 5/5 then they can go in as fixes I think. > > > > I had replied to Andy's comments - I'm prefer with my version than his > suggestion: > > "I'm not keen on that alternative as what it suggests is actually a > pointer comparison, and even if the user realizes that they may instead > use "strlen(label) == 0", when they shouldn't be assuming that a null > terminator is present in the array. I avoided mentioning "string" and > kept it in terms of the char array for the same reason." My point is to make documentation less cryptic (= less programming language stylish). If you can rephrase it that way - nice! Otherwise, I leave this to Linus.
On Wed, Oct 14, 2020 at 08:14:20PM +0300, Andy Shevchenko wrote: > On Tue, Oct 13, 2020 at 7:34 PM Kent Gibson <warthog618@gmail.com> wrote: > > On Tue, Oct 13, 2020 at 03:21:47PM +0200, Linus Walleij wrote: > > > On Thu, Oct 8, 2020 at 5:46 PM Bartosz Golaszewski > > > <bgolaszewski@baylibre.com> wrote: > > ... > > > > I am waiting for Kent to respin them addressing Andy's comments > > > on patch 5/5 then they can go in as fixes I think. > > > > > > > I had replied to Andy's comments - I'm prefer with my version than his > > suggestion: > > > > "I'm not keen on that alternative as what it suggests is actually a > > pointer comparison, and even if the user realizes that they may instead > > use "strlen(label) == 0", when they shouldn't be assuming that a null > > terminator is present in the array. I avoided mentioning "string" and > > kept it in terms of the char array for the same reason." > > My point is to make documentation less cryptic (= less programming > language stylish). > If you can rephrase it that way - nice! Otherwise, I leave this to Linus. > I agree with your point - including code snippets should be a last resort. But sometimes that is the most effective way to do it. Cheers, Kent.
On Mon, Oct 5, 2020 at 9:03 AM Kent Gibson <warthog618@gmail.com> wrote: > Kent Gibson (5): > gpio: uapi: fix kernel-doc warnings > gpio: uapi: comment consistency > gpio: uapi: kernel-doc formatting improvements > gpio: uapi: remove whitespace > gpio: uapi: clarify the meaning of 'empty' char arrays I applied this to my fixes branch now. Thanks! Yours, Linus Walleij