On Tue, 15 Jan 2019 22:37:01 +0200
"Joel Nider" [off-list ref] wrote:

Jonathan Corbet [off-list ref] wrote on 01/15/2019 08:08:54 PM:

quoted

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