linux-kernel - Re: [PATCH 2/2] docs: document linked lists

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <87v7p48vd6.fsf@trenco.lwn.net>
Date: Mon, 09 Jun 2025 15:20:53 -0600
From: Jonathan Corbet <corbet@....net>
To: Nicolas Frattaroli <nicolas.frattaroli@...labora.com>
Cc: kernel@...labora.com, linux-doc@...r.kernel.org,
 linux-kernel@...r.kernel.org, Nicolas Frattaroli
 <nicolas.frattaroli@...labora.com>
Subject: Re: [PATCH 2/2] docs: document linked lists

Nicolas Frattaroli <nicolas.frattaroli@...labora.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@...labora.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.

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

Thanks,

jon