Elad Efrat wrote:
> Because we will not reach an understanding of what should be used for
> wording in a man-page, I'll take a step back

And that's probably a livable outcome for now. There is a man page where
there wasn't one, our meta-discussion of it is on record in this thread,
and should you, I, or someone else entirely be struck by some future
inspiration to improve the page without loss of information quality, why,
there it'll be.

> hard to understand for people who
> (a) never seen the code that implements the API

Ok ... I /intended/ it to be usable for exactly that class of readers;
I strongly believe the job of a man page is to present the information
necessary to use an API without forcing the reader to UTSL to fill in
the blanks.[*]  Therefore if I fell short of this goal I welcome
constructive suggestions from anyone who sees a way to get closer.

> (b) want to start
> coding without caring about and reading through the gory details.

I am less moved by this point because I'm not sure that's the
target audience for a kernel developer's manual.

Thanks for the comments,
-Chap


[*] this is also important for a quality initiative: it is difficult
to verify, validate, or regression-test if there does not exist some
document that sets out the semantics independently of the code itself.