lkml.org 
[lkml]   [2019]   [Jan]   [15]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH v2 2/2] docs-rst: userspace: update verbs API details
On Tue, 15 Jan 2019 22:37:01 +0200
"Joel Nider" <JOELN@il.ibm.com> wrote:

> Jonathan Corbet <corbet@lwn.net> wrote on 01/15/2019 08:08:54 PM:
> > 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?

We are not attempting to duplicate the man pages; there's been occasional
talk of bringing them into the kernel tree, but enthusiasm for that is
scarce for a number of good reasons. But there's a lot of information
about the user-space API that isn't in the man pages, including the piece
you are converting to RST.

For a huge example, look at the massive v4l2 UAPI documentation that's in
the kernel; that will never really fit into the man-page model. (And yes,
it belongs in the userspace-api directory but isn't there for $REASONS).

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

For something like this, driver-api seems like the right place. Someday,
in some glorious future, it could contain a full manual on how these
drivers are written, using all of the nice kerneldoc comments that already
exist under drivers/infiniband.

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

I'd rather see you put the new stuff under Documentation/driver-api, either
in a standalone file or in a new subdirectory.

Thanks for your patience with this! We really do want people to contribute
more documentation, and I feel bad when it seems like I'm making it
harder. My hope is that it will pay off in the long run; I think there are
signs already that this is happening.

Thanks,

jon

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