Re: [PATCH locking/atomic 18/19] locking/atomic: Refrain from generating duplicate fallback kernel-doc

[Peter Zijlstra <peterz@infradead.org>]

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.