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

[Mark Brown <broonie@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 2640 bytes --]

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:

> > >  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:
> 
> 	Kernel API documentation
> 	------------------------
> 
> That's the case of media, input, hwmon, and so many other subsystems.

> Yet, you're right: this implies that there will be some things
> to be done, as the long-term documentation should be like:
> 
> 	Documentation/admin-guide/{media, input, hwmon, spi, ...}
> 	Documentation/userspace-api/{media, input, hwmon, spi, ...}
> 	Documentation/driver-api/{media, input, hwmon, spi, ...}

> 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?  It feels very arbatrary and unhelpful for things
like spidev where theuser is going to be writing a program.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]