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

[Joel Nider]

Jonathan Corbet <corbet@xxxxxxx> wrote on 01/15/2019 11:38:59 PM:

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

My next task is to update the man pages for rdma-core since I touched 
libibverbs as well (the _other_ side of this API). So I just want to make 
sure everything is documented exactly once (no more, no less) and in the 
correct place.

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

I took a quick look at what is already there, and I don't see how the RDMA 
stuff fits. It looks like the majority is about various busses (SPI, PCI, 
I2C, USB, etc) or other general platform support (clk, edac) that I would 
use when writing a driver. My changes are very infiniband-specific, and 
user-facing and don't really seem to fit in with the aforementioned 
modules. It seems to me that if it does not belong in userspace-api, then 
leaving it where it is is the best choice.

Regards,
Joel