Re: [TECH TOPIC] Kernel documentation - update and future directions

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Sat, 30 Aug 2025 17:08:53 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Laurent Pinchart <laurent.pinchart@ideasonboard.com> writes:
> 
> >> > Last year we tried an experiment with a bit of funding from the LF to
> >> > create a bit of paid documentation; for a number of reasons, that
> >> > experiment did not work out.  But it seems there should be a way to make
> >> > some forward progress on this front.  
> >
> > Is there anything we can learn from that failure and that number of
> > reasons to make the next attempt more successful ?  
> 
> I think that the experiment didn't work for a couple of reasons:
> 
> - The topic area that we settled upon was a relatively advanced one, we
>   really should have started with something simpler.
> 
> - The writer who was assigned was not really up to the task; I found
>   myself repeatedly having to explain basic aspects of the C programming
>   language, for example.  That made it almost impossible to get a
>   satisfactory document out of the process, made worse by the first
>   reason listed above.

The way I see, there are several orthogonal tasks.

1) Book set organization

The first one would almost certainly require LF or someone else sponsor
a person with lots of experience on organizing and reviewing technical
books that worked on similar projects.

Such person would be starting from top to down, organizing the books
on a way that the basic knowledge would be covered at the first chapters,
and more advanced items at the end, and missing chapters will contain
skeleton ReST files on it to be filled by someone else. After having
it, review the text, specially for the less technical chapters, to
ensure that it is accessible to kernel newbies.

2) uAPI documentation

This requires highly skilled people or advanced userspace developers,
and should be done subsystem by subsystem. 

We did that on media several years ago, and, although not perfect, 
I do think that we cover almost everything for uAPI, with examples, 
tables images etc.

From my experience, uAPI is easier to document than kAPI, as it doesn't
change that much (not counting sysfs/debugfs/configfs).

On media, we started enforcing documentation for all new media uAPI.
We then reviewed the gaps and filled in the blanks.

3) ABI documentation: sysfs, configfs, debugfs

Such ABIs are a different best: we have dozens of thousands of sysfs symbols
on a server. Last time I checked, most undocumented.

I wrote a function at get_abi tool to help finding the gaps: it can help
identifying missing gaps by converting ABI descriptions into regular
expressions and check against the real sysfs nodes found at the system(*). 

I'd say that someone without intermediate C knowledge can probably use it
to produce a lot of missing ABI documentation.

(*) The tool itself can easily be modified to also handle debugfs/configfs,
    but there are too many gaps at sysfs. I would start with them.

4) kernel-doc kAPI

It shouldn't be that hard to do the same for kernel-doc kAPI documentation:
kernel-doc now can parse the entire tree with:

	$ scripts/kernel-doc .

Someone can easily use it to discover the current gaps at the docs that
have already some kernel-doc markups and identify what of them aren't
yet placed under Documentation/ ".. kernel-doc::" markups.

So, I'd say the first step here would be to ensure that 100% of the
docs are there somewhere. Alternatively, we could place all the rest
of functions with kernel-doc markups outside Documentation inside an
"others/" book - or even "<subsystem>/others/", and then gradually move
them to the right places.

5) kAPI itself

Except for trivial cases, I don't think that only kernel-doc is
enough. On most of the cases, a document describing the main
concepts and the design behind the kAPI is needed. Almost certainly
only core developers and maintainers within each subsystem can
write those.

> What it comes down to, perhaps, is the same old problem: the people who
> understand the problem domain well enough to document it can generally
> make a more comfortable living creating more undocumented code instead.

True, but I guess this is valid mostly for (5).

Thanks,
Mauro