Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Thu, 11 May 2023 22:48:06 +0200
From:   Peter Zijlstra <peterz@infradead.org>
To:     "Paul E. McKenney" <paulmck@kernel.org>
Cc:     Mark Rutland <mark.rutland@arm.com>, linux-kernel@vger.kernel.org,
        x86@kernel.org, akiyks@gmail.com, linux-doc@vger.kernel.org,
        kernel-team@meta.com, Will Deacon <will@kernel.org>,
        Boqun Feng <boqun.feng@gmail.com>
Subject: Re: [PATCH locking/atomic 18/19] locking/atomic: Refrain from
 generating duplicate fallback kernel-doc
Message-ID: <20230511204806.GA2298690@hirez.programming.kicks-ass.net>
References: <19135936-06d7-4705-8bc8-bb31c2a478ca@paulmck-laptop>
 <20230510181717.2200934-18-paulmck@kernel.org>
 <ZF0haDfyL3At3Ijw@FVFF77S0Q05N.cambridge.arm.com>
 <20230511193856.GA2296992@hirez.programming.kicks-ass.net>
 <c619d689-e7b5-4136-9bd3-8f41954f43cd@paulmck-laptop>
 <20230511200142.GC2296992@hirez.programming.kicks-ass.net>
 <613a2d06-30f1-4140-aa6c-16d5298d9909@paulmck-laptop>
 <20230511204633.GF2296992@hirez.programming.kicks-ass.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20230511204633.GF2296992@hirez.programming.kicks-ass.net>
Precedence: bulk

On Thu, May 11, 2023 at 10:46:33PM +0200, Peter Zijlstra wrote:
> On Thu, May 11, 2023 at 01:25:18PM -0700, Paul E. McKenney wrote:
> > On Thu, May 11, 2023 at 10:01:42PM +0200, Peter Zijlstra wrote:
> > > On Thu, May 11, 2023 at 12:53:46PM -0700, Paul E. McKenney wrote:
> > > > Do you have an alternative suggestion for generating the kernel-doc?
> > > > The current lack of it is problematic.
> > > 
> > > I've never found a lack of kernel-doc to be a problem. And I'm very much
> > > against complicating the scripts to add it.
> > 
> > I am sure that you have not recently found the lack of kernel-doc for
> > the atomic operations to be a problem, given that you wrote many of
> > these functions.
> 
> Sure; but I meant in general -- I've *never* used kernel-doc. Comments I
> occasionally read, and sometimes they're not even broken either, but
> kernel-doc, nope.
> 
> > OK, you mentioned concerns about documentation people nitpicking.  This
> > can be dealt with.  The added scripting is not that large or complex.
> > 
> > > Also, there's Documentation/atomic_t.txt
> > 
> > Yes, if you very carefully read that document end to end, correctly
> > interpreting it all, you will know what you need to.  Of course, first
> > you have to find it.  And then you must avoid any lapses while reading
> > it while under pressure.  Not particularly friendly to someone trying
> > to chase a bug.
> 
> It's either brief and terse or tediously long -- I vastly prefer the
> former, my brain can much better parse structure than English prose.
> 
> Also, I find, pressure is never conductive to anything, except prehaps
> cooking rice and steam trains (because nothing is as delicous as a
> pressure cooked train -- oh wait).
> 
> Add enough pressure and the human brain reduces to driven and can't read

Just in case it weren't clear: s/driven/drivel/

> even the most coherent of text no matter how easy to find.
> 
> In such situations it's for the manager to take the pressure away and
> the engineer to think in relative peace.