Re: [PATCH v2 2/2] docs-rst: userspace: update verbs API details

[Jonathan Corbet <corbet@lwn.net>]

On Tue, 15 Jan 2019 18:29:59 +0200
"Joel Nider" <JOELN@il.ibm.com> wrote:

> > I think this is a horrible direction to take.  The current document is
> > clearly for _users_.  All this documentation you've added is for kernel
> > hackers.  It needs to go in a different file, or not be added at all.
> >   
> Hmm, that's a bit heavy-handed in my opinion. If you look at what is 
> currently under "Userspace API", there are a total of 4 files - not 
> exactly what I would call comprehensive documentation of the Linux kernel 
> interface. 

One has to start somewhere - I'm glad to see you adding to it.

> So the option of not adding more documentation simply because 
> it is in the wrong section seems a bit defeatist (I think we can all agree 
> more kernel docs is a good thing). So let's assume for the moment that it 
> _should_ be added, and that we are discussing _where_.

I think we definitely want to add it.

> Yes, the document I 
> am modifying has a bit of a mash of pure userspace API - functions and 
> details that application developers must know - and the lower level 
> details that are more useful for someone who wishes to extend this 
> interface. The existing documentation (specifically unshare) also suffers 
> from the same problem. There is a section (7) called "Low Level Design" 
> which documents very much the same level of detail as the Infiniband doc, 
> so this seems to be at least consistent.
> I think there is a deeper issue - as an application developer, I would 
> only look at this kernel documentation as a last resort. #1 is the 'man' 
> pages, #2 is web search for an example (I know for many it's the other way 
> around). So who really looks at this documentation? I say the vast 
> majority is kernel hackers. So yes, this is about the user-facing API, but 
> not from the application writer's perspective - it should be about how to 
> create a consistent API for users, from the kernel hacker's perspective.

The intent behind the user-space API manual is to document the user-space
API; it's meant to be read by people writing applications and such.
Perhaps they find it with a web search, but it will be there for them, one
hopes, when they want it.

The project of reworking the kernel documentation to be more comprehensive
and more focused on its readers, rather than, as Rob Landley once put it,
"a gigantic mess, currently organized based on where random passers-by put
things down last" is still in an early stage.  But that doesn't mean that
we shouldn't try to always move in the right direction.  So I agree with
Willy that this particular text is better suited to the driver-API
manual.  Even if a bare bit of information on its own there for now, it's
a starting place.  Can I ask you to do that, please?

Thanks,

jon