On Mon, Jan 15, 2024 at 1:49 AM Kent Gibson <warthog618@xxxxxxxxx> wrote: > > My new year's resolution was to improve the documentation of the > character device API and gpio in general, so here we are. > > Wrt the formatting and file breakdown, I've taken inspiration from > the userspace-api/media documentation. > > Patch 1 adds documentation for the current chardev uAPI. I've added > it to the userspace-api book, as that is the most obvious place a > reader would look for it, but have also provided links from the > admin-guide book where the gpio docs currently reside. > > I realise MAINTAINERS should be updated with > Documentation/userspace-api/gpio/, but the split out of GPIO UAPI > hasn't made it into gpio/for-next yet, so I was unsure of how to > handle that. > > Patch 2 updates the gpio-cdev ABI documentation to reference the > chardev documentation as well as gpio.h. > > Patch 3 updates the sysfs-gpio ABI documentation to reference the > gpio-cdev ABI that obsoletes it. > > Patch 4 relocates the sysfs API doc to stress its deprecation by > moving it to a new obsolete section, again in userspace-api but > with a similar section in the admin-guide. The obsolete section > also serves as a placeholder for subsequent changes. > > Patch 5 updates the sysfs API doc to reference the chardev > documentation rather than gpio.h and make use of reST formatting. > > Patch 6 adds documentation for the obsolete v1 version of the > chardev uAPI. It is obsolete, but still useful to have, if > nothing else to help identify the differences between v1 and v2. > > Patch 7 capitalizes the title of the admin-guide/gpio to match > the other subsystems and the userspace-api book. > > Patch 8 adds an obsolescence note to the gpio-mockup, as it is > obsoleted by the gpio-sim. > > Patch 9 moves the gpio-mockup doc into the obsolete section. > > I've got some minor updates for the kernel doc in gpio.h as well, > but they make sense on their own so I've sent those separately > to keep the cross-posting to a minimum. > > I realise the only thing less exciting than writing documentation > is reviewing it, so my apologies and thanks in advance if you > have the fortitude to attempt such a scintillating endeavour. > Not all heroes wear capes. Thanks for doing this Kent! Queued the series for v6.9. [snip]
