lkml.org 
[lkml]   [2019]   [Jan]   [15]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
SubjectRe: [PATCH v2 2/2] docs-rst: userspace: update verbs API details
From
Date
Jonathan Corbet <corbet@lwn.net> wrote on 01/15/2019 08:08:54 PM:

> From: Jonathan Corbet <corbet@lwn.net>
> To: "Joel Nider" <JOELN@il.ibm.com>
> Cc: Matthew Wilcox <willy@infradead.org>, Doug Ledford
<dledford@redhat.com>,
> Jason Gunthorpe <jgg@ziepe.ca>, Leon Romanovsky <leon@kernel.org>,
linux-
> doc@vger.kernel.org, linux-kernel@vger.kernel.org, Mike Rapoport
<rppt@linux.ibm.com>
> Date: 01/15/2019 08:09 PM
> Subject: Re: [PATCH v2 2/2] docs-rst: userspace: update verbs API
details
>
> 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.

So is the intent then to duplicate what is already in 'man'? Why would we
want 2 different locations for basically the same information? Wouldn't it
make more sense to just put these few details into appropriate 'man'
pages?

> 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.

It looks like I misunderstood the purpose of the "userspace API" section
then. So is there a section that is meant for a guide on how to write an
interface function?

> 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?

OK, just to be clear - you are asking me to leave the original file as-is
(well, after .rst conversion) but move it to the new location
(Documentation/userspace-api), and put my new content into a new file in
the old location (Documentation/infiniband)?

> Thanks,
>
> jon
>


\
 
 \ /
  Last update: 2019-01-15 21:38    [W:0.083 / U:10.148 seconds]
©2003-2018 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site