Re: Follow-up on Linux-kernel code accessibility

["Theodore Tso" <tytso@mit.edu>]

On Fri, Dec 26, 2025 at 11:48:30AM -0500, Steven Rostedt wrote:
> Agreed, but knowing what the function is doing should give you some idea of
> how it is doing it.
> 
>   "Loop doing repeated quiescent-state forcing until the grace period ends."
> 
> Is the only description of "what the function is doing", but it gives you
> no clue to why it's using those magic numbers. There should be comments
> about how the magic numbers relate to the what.

Sure, but rcu_gp_fqs_loop() is a static, internal function.  I agree
that better documentation would be usefui for people who want to
modify the internals of the RCU infrastructure, but it's not something
that should be in kernel documentation for newcomers to kernel
development.

When we talk about making the kernel code more accessible, it's really
important to keep in mind that different audiences may have different
needs, and too much information can be just as confusing as too
little.  It seems likely that most newcomers aren't going to be
looking to make changes to important systems like RCU.

That being said, even though most newcomers aren't probably going to
be making changes to file systems, as a file system maintainer I
admittedly to have a vested interest in making easier for
intermediate-level kernel developers who might take an interest to
ext4 development to have an easy path to do so.  So I get where Paul
is coming from.

When we're talking about making the kernel code more accessible, we
need need to be very explicit about which target audiences we are
targetting, because the strategies might be different for different
readers.

						- Ted