Message-ID: <20796f12-5a8b-4a4d-96f7-4604c782ec21@paulmck-laptop>
Date:   Thu, 11 May 2023 14:24:41 -0700
From:   "Paul E. McKenney" <paulmck@...nel.org>
To:     Peter Zijlstra <peterz@...radead.org>
Cc:     Mark Rutland <mark.rutland@....com>, linux-kernel@...r.kernel.org,
        x86@...nel.org, akiyks@...il.com, linux-doc@...r.kernel.org,
        kernel-team@...a.com, Will Deacon <will@...nel.org>,
        Boqun Feng <boqun.feng@...il.com>
Subject: Re: [PATCH locking/atomic 18/19] locking/atomic: Refrain from
 generating duplicate fallback kernel-doc

On Thu, May 11, 2023 at 10:48:06PM +0200, Peter Zijlstra wrote:
> 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.

I am not arguing that *you* need kernel-doc, and I must admit that I
also tend to look much more carefully at the code than the comments.
But not everyone has your level of code-reading talent, nor does everyone
have my half century of practice reading code.

(OK, OK, so it won't really be a half century until this coming
September!)

> > > 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.

Agreed, English prose does have its challenges, no two ways about it.

But in order to successfully communicate with someone, it is necessary
to start where that person is, not where we might prefer them to be.
And there are quite a few people who benefit from a bit of English prose.

As long as we are picking on languages, there are some who assert that
Dutch is the easiest language for native English speakers to learn.
I know nothing myself, but for the purposes of this discussion, I will
assume that this is because Dutch uses similar words but is better
structured than is English.  As opposed, say, that Dutch is messed up
almost exactly the same ways that English is.  ;-)

> > 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/

You know, my brain auto-corrected and I didn't even notice.  And I still
sometimes wonder why I fail to spot bugs.  ;-)

> > 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.

I won't argue, having forced that a few times back in past lives.
"No, you don't have to get this done by Friday, and if anyone tells
you differently, you tell them to talk to me."  In one memorable case,
once pressure was relieved, they actually got it done before Friday.

Still, that is no reason to make that poor engineer's life even harder.
After all, there never have been more than a handful of managers that
I had that kind of influence over.  Plus there is the occasional true
emergency, though admittedly far fewer true emergencies that proclaimed
emergencies.

But suppose your response to someone nitpicking the atomic-operation
kernel-doc could simply be "Not my problem, go talk to Paul."  I would
of course be plenty happy to respond appropriately to people who expect
to read a long series of kernel-doc entries for atomic operations as
if it was a novel.  For some appropriate definition of "appropriately",
of course.

Would that help?

							Thanx, Paul

Powered by blists - more mailing lists