Re: [RFC PATCH 0/7] x86/entry: Atomic statck switching for IST

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On 06. 04. 23, 12:47, Peter Zijlstra wrote:
On Thu, Apr 06, 2023 at 12:35:24PM +0200, Jiri Slaby wrote:
On 06. 04. 23, 12:12, Peter Zijlstra wrote:
On Tue, Apr 04, 2023 at 07:03:45PM +0200, Paolo Bonzini wrote:
On 4/4/23 05:17, Lai Jiangshan wrote:
The cover letter has 800+ lines of comments.  About 100-300 lines
of comments will be moved into the code which would make the diffstat
not so appealing.

Removing assembly from arch/x86/entry/ and adding English to Documentation/?
That's _even more_ appealing. :)

I *much* prefer in-code comments to random gibberish that's instantly
out of date squirreled away somewhere in an unreadable format in
Documentation/

+1 as one can link comments in the code to Documentation easily nowadays.
They are sourced and end up in the generated Documentation [1] then. One
only needs to type the kernel-doc properly.

Urgh, so that kernel doc stuff can defeat its purpose too. Some of that
is so heavily formatted it is unreadable gibberish just like
Documentation/ :/

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

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.

thanks,
--
js




[Index of Archives]     [KVM ARM]     [KVM ia64]     [KVM ppc]     [Virtualization Tools]     [Spice Development]     [Libvirt]     [Libvirt Users]     [Linux USB Devel]     [Linux Audio Users]     [Yosemite Questions]     [Linux Kernel]     [Linux SCSI]     [XFree86]

  Powered by Linux