Re: [PATCH 2/2] docs: document linked lists

[Nicolas Frattaroli <nicolas.frattaroli@collabora.com>]

On Monday, 9 June 2025 23:20:53 Central European Summer Time Jonathan Corbet wrote:
> Nicolas Frattaroli <nicolas.frattaroli@collabora.com> writes:
> 
> > The kernel contains various generic data structures that should ideally
> > not be reinvented. However, it often fails to document the usage of
> > these in the in-tree kernel documentation beyond just a listing of
> > header symbols in the very lengthy kernel-api docs page. This is fine
> > for things that have simple invocations, but occasionally things devolve
> > into several layers of concatenating macros, which are subpar for humans
> > to parse.
> >
> > Begin making a small impact by adding some rudimentary example-driven
> > documentation for the linked list type. It's far from exhaustive, as
> > many list modification functions are currently not mentioned. However,
> > it covers the basics and directs readers towards further documentation
> > should they be interested in concurrency.
> >
> > Signed-off-by: Nicolas Frattaroli <nicolas.frattaroli@collabora.com>
> > ---
> >  Documentation/core-api/index.rst |   1 +
> >  Documentation/core-api/list.rst  | 390 +++++++++++++++++++++++++++++++++++++++
> >  2 files changed, 391 insertions(+)
> 
> So I'm only now getting around to a belated look at this.  I like it
> overall, but I do have a couple of comments:
> 
> - Is there any way to talk you into replacing all of the graphviz
>   diagrams with ascii art in literal blocks?  All the dot stuff makes
>   for pretty HTML, but is entirely unreadable for people looking at the
>   plain-text docs.

Yeah, the dot was more easily understood at one point but then I decided
I wanted to wrestle the layout and add backedges and then not make the
backedges look horrible. Now it's a mess. I think I can easily be
convinced to replace it with ASCII art in literal blocks. On that note,
I wonder if there is a tool to translate simple ASCII graphs into dot
and then whatever output from that, which would be the ideal solution
here to encode semantic meaning for both audiences.

I'll definitely drop the back edges from the diagrams though, they
only make things more confusing.

> 
> - All of the kerneldoc stuff for list.h is currently pulled into
>   kernel-api.rst.  Should we perhaps move it over here?

I think that's a good idea once the new documentation exhaustively
covers everything. Pulling it into both places generates warnings,
which is why I didn't do it for the functions I already did document.
And doing it only for some and not others needlessly spreads things
out across two pages, though maybe this is best dealt with having a
"dumping ground" in each section for other functions related to that
section, so that we have an exhaustive function listing even if no
usage examples are provided.

I will work on a v2 today which addresses your concerns, and expands
on the documentation to also include some list modification functions.

> 
> Thanks,
> 
> jon
> 

Kind regards,
Nicolas Frattaroli