Matthew Wilcox <willy@xxxxxxxxxxxxx> wrote on 01/15/2019 05:31:28 PM: > From: Matthew Wilcox <willy@xxxxxxxxxxxxx> > To: Joel Nider <joeln@xxxxxxxxxx> > Cc: Jonathan Corbet <corbet@xxxxxxx>, Jason Gunthorpe <jgg@xxxxxxxx>, Leon > Romanovsky <leon@xxxxxxxxxx>, Doug Ledford <dledford@xxxxxxxxxx>, Mike > Rapoport <rppt@xxxxxxxxxxxxx>, linux-doc@xxxxxxxxxxxxxxx, linux-kernel@xxxxxxxxxxxxxxx > Date: 01/15/2019 05:31 PM > Subject: Re: [PATCH v2 2/2] docs-rst: userspace: update verbs API details > > On Tue, Jan 15, 2019 at 12:26:31PM +0200, Joel Nider wrote: > > It is important to understand the existing framework when implementing > > a new verb. The majority of existing API functions are implemented using > > the write syscall, but this has been superceded by the ioctl syscall > > for new commands. This patch updates the documentation regarding how > > to go about implementing a new verb, focusing on the new ioctl > > interface. > > > > The documentation is far from complete, but this is a good step in the > > right direction. Future patches can add more detail according to need. > > Also, the interface is still undergoing substantial changes so an > > effort was made to document only the stable parts so as to avoid > > incorrect information since documentation changes tend to lag behind > > code changes. > > 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. 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_. 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. Joel
