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

[Jonathan Corbet <corbet@lwn.net>]

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