linux-kernel - Re: [PATCH 0/5] gpio: uapi: documentation improvements

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20201014233514.GA34185@sol>
Date:   Thu, 15 Oct 2020 07:35:14 +0800
From:   Kent Gibson <warthog618@...il.com>
To:     Andy Shevchenko <andy.shevchenko@...il.com>
Cc:     Linus Walleij <linus.walleij@...aro.org>,
        Bartosz Golaszewski <bgolaszewski@...libre.com>,
        LKML <linux-kernel@...r.kernel.org>,
        linux-gpio <linux-gpio@...r.kernel.org>
Subject: Re: [PATCH 0/5] gpio: uapi: documentation improvements

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@...il.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@...libre.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.