[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <20230406123755.GC392176@hirez.programming.kicks-ass.net>
Date: Thu, 6 Apr 2023 14:37:55 +0200
From: Peter Zijlstra <peterz@...radead.org>
To: Jiri Slaby <jirislaby@...nel.org>
Cc: Paolo Bonzini <pbonzini@...hat.com>,
Lai Jiangshan <jiangshanlai@...il.com>,
Dave Hansen <dave.hansen@...el.com>,
linux-kernel@...r.kernel.org,
Lai Jiangshan <jiangshan.ljs@...group.com>,
"H. Peter Anvin" <hpa@...ux.intel.com>,
Andi Kleen <ak@...ux.intel.com>,
Andrew Cooper <andrew.cooper3@...rix.com>,
Andy Lutomirski <luto@...nel.org>,
Asit Mallick <asit.k.mallick@...el.com>,
Cfir Cohen <cfir@...gle.com>,
Dan Williams <dan.j.williams@...el.com>,
David Kaplan <David.Kaplan@....com>,
David Rientjes <rientjes@...gle.com>,
Erdem Aktas <erdemaktas@...gle.com>,
Jan Kiszka <jan.kiszka@...mens.com>,
Joerg Roedel <joro@...tes.org>,
Juergen Gross <jgross@...e.com>,
Kees Cook <keescook@...omium.org>,
Kirill Shutemov <kirill.shutemov@...ux.intel.com>,
Kuppuswamy Sathyanarayanan <knsathya@...nel.org>,
Linus Torvalds <torvalds@...ux-foundation.org>,
Mike Stunes <mstunes@...are.com>,
Raj Ashok <ashok.raj@...el.com>,
Sean Christopherson <seanjc@...gle.com>,
Thomas Gleixner <tglx@...utronix.de>,
Tom Lendacky <thomas.lendacky@....com>,
Tony Luck <tony.luck@...el.com>, kvm@...r.kernel.org,
linux-coco@...ts.linux.dev, x86@...nel.org
Subject: Re: [RFC PATCH 0/7] x86/entry: Atomic statck switching for IST
On Thu, Apr 06, 2023 at 01:04:16PM +0200, Jiri Slaby wrote:
> Definitely it _can_ defeat the purpose and be heavily formatted.But it
> doesn't have to. It's like programming in perl.
>
> What I had in mind was e.g. "DOC: TTY Struct Flags":
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/linux/tty.h#n261
* TTY_THROTTLED
* Driver input is throttled. The ldisc should call
* :c:member:`tty_driver.unthrottle()` in order to resume reception when
* it is ready to process more data (at threshold min).
That whole :c:member:'tty_driver.unthrottle()' is an abomination and
has no place in a comment.
> Resulting in:
> https://www.kernel.org/doc/html/latest/driver-api/tty/tty_struct.html#tty-struct-flags
>
> Both the source and the result are quite readable, IMO. And the markup in
> the source is not mandatory, it's only for emphasizing and hyperlinks.
>
> As I wrote, you can link the comment in the code. But definitely you don't
> have to, if you don't want. I like the linking in Documentation as I can put
> the pieces from various sources/headers together to one place and build a
> bigger picture.
>
> > I really detest that whole RST thing, and my solution is to explicitly
> > not write kerneldoc, that way the doc generation stuff doesn't complain
> > and I don't get random drive by patches wrecking the perfectly readable
> > comment.
>
> Sure. Rst _sources_ are not readable, IMO. Only generated man pages or html
> are.
But code comments are read in a text editor, not a browser. Hence all
the markup is counter productive.
Why would you go read something in a browser if you have the code right
there in a text editor?
Powered by blists - more mailing lists