On Tue, Jan 9, 2024 at 4:00 PM 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 relocates the sysfs API doc to stress its deprecation by > moving it to a new deprecated section, again in userspace-api but > with a similar section in the admin-guide. The deprecated section > also provides a placeholder for subsequent changes. > > Patch 3 updates the sysfs API doc to reference the chardev > documentation rather than gpio.h. > > Patch 4 adds documentation for the deprecated v1 version of the > chardev uAPI. It is deprecated, but still useful to have, if > nothing else to help identify the differences between v1 and v2. > > Patch 5 capitalizes the title of the admin-guide/gpio to match > the other subsystems and the userspace-api book. > > Patch 6 adds a deprecation note to the gpio-mockup, as it is > obsoleted by the gpio-sim. > > Patch 7 moves the gpio-mockup doc into the deprecated 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'll send those separately > 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. Thanks a lot for doing this! ... > Documentation/userspace-api/gpio/chardev.rst | 114 ++++++++++++++++ > .../userspace-api/gpio/chardev_v1.rst | 129 ++++++++++++++++++ Shouldn't it be better to have chardev_v2.rst along with chardev.rst to be a link to it? ... May we actually state in the documentation that sysfs is subject to remove at some point? -- With Best Regards, Andy Shevchenko
