Re: [RFC PATCH v2 0/1] bpf, docs: structured overview of verifier

[Jonathan Corbet <corbet@lwn.net>]

Burak Emir <bqe@google.com> writes:

> This is an RFC for adding overview documentation for the BPF verifier.
>
> The existing verifier.rst has detail but IMHO it lacks structure and
> background. Here is my humble proposal to make the verifier docs
> more helpful for newcomers.
>
> Finding a balance between overview and detail in documentation is 
> never easy. The idea here is to describe abstract interpretation and have
> enough information that anyone interested can learn what is going on. 
>
> Please let me know what you think. I used Gemini 3 to get a first draft,
> which I then checked word-for-word and reworked.

I only got the cover letter for the second version, so these overall
comments are based on the first.

- Please stick to the 80-column line limit for text material; we want
  people to be able read it.

- Why split this into five different files?  It is not a massive amount
  of material; spreading it out just makes the reader work harder.

- It is overly heavy on the markup.  If nothing else, function
  references should just be function(), without ``literal`` markup; that
  lets the automarkup code do its thing.  Same with "struct foo".

Hopefully the BPF folks can take a more substantive look as well.

jon