Re: [PATCH 04/22] docs: spi: convert to ReST and add it to the kABI bookset

[Mauro Carvalho Chehab <mchehab+samsung@kernel.org>]

Em Mon, 22 Jul 2019 16:21:10 +0100
Mark Brown <broonie@kernel.org> escreveu:

> On Mon, Jul 22, 2019 at 10:10:35AM -0300, Mauro Carvalho Chehab wrote:
> > Mark Brown <broonie@kernel.org> escreveu:  
> 
> > > On Mon, Jul 22, 2019 at 08:07:31AM -0300, Mauro Carvalho Chehab wrote:  
> > > > While there's one file there with briefily describes the uAPI,
> > > > the documentation was written just like most subsystems: focused
> > > > on kernel developers. So, add it together with driver-api books.    
> 
> > > Please use subject lines matching the style for the subsystem.  This
> > > makes it easier for people to identify relevant patches.  
> 
> > Sure. Do you prefer this prefixed by:  
> 
> > 	spi: docs:  
> 
> > Or with something else?  
> 
> Anything starting with spi:

Ok.

> 
> > > >  Documentation/spi/{spidev => spidev.rst}      |  30 +++--    
> > > 
> > > This is clearly a userspace focused document rather than a kernel
> > > internal one.  
> > 
> > True. What I've been doing so far is, for all drivers that I'm converting
> > with carries more than one documentation type (kABI, uABI and/or 
> > admin-guide) is to keep the directory as-is, adding them under
> > this section at Documentation/index.rst:

...

> > Btw, if you look at spidev file, it contains stuff for both
> > userspace-api:
> > 
> > 	"SPI devices have a limited userspace API, supporting basic half-duplex
> > 	 read() and write() access to SPI slave devices.  Using ioctl() requests,"  
> 
> > And for admin-guide:  
> 
> > 	"For a SPI device with chipselect C on bus B, you should see:
> > 
> > 	    /dev/spidevB.C ... character special device, major number 153 with
> > 		a dynamically chosen minor device number. "  
> 
> I think that split is higly artificial...
> 
> > So, if we're willing to move it, the best is to do on a separate patch
> > with would split its contents into two files: admin-guide/spi-devices.rst and 
> > userspace-api/spi-api.rst.  
> 
> ...
> 
> > Ideally, we should split what's there at media/uapi into admin-guide
> > and userspace-api, but this would mean *a lot* of efforts. Not sure
> > if it is worth the effort.  
> 
> Is the admin/API stuff even sensible for things that are more embedded
> or desktop focused?  

Yes. Btw, the plan is to add everything under Documentation/ABI at the
admin guide (parsed via some scripts).

> It feels very arbatrary and unhelpful for things
> like spidev where theuser is going to be writing a program.

I tend to agree with you. Doing such split may actually make things
worse for app developers, without providing much benefit for sysadmins.

I sent today an e-mail to the KS discussion ML about that, as, IMHO,
this is something that we should discuss at the Documentation track
there.

While the idea of having users/sysadmin-faced stuff at admin-guide
seems to be nice, doing it for driver-specific stuff could be overkill,
and will mean a lot of extra work.

Thanks,
Mauro