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

[Jonathan Corbet <corbet@lwn.net>]

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.

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

Thanks,

jon