Received-SPF: pass (google.com: domain of linux-kernel+bounces-21374-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) client-ip=147.75.199.223;
Precedence: bulk
MIME-Version: 1.0
References: <20240109135952.77458-1-warthog618@gmail.com>
In-Reply-To: <20240109135952.77458-1-warthog618@gmail.com>
From: Andy Shevchenko <andy.shevchenko@gmail.com>
Date: Tue, 9 Jan 2024 22:00:26 +0200
Message-ID: <CAHp75Ve05bAK-ehZZ7XSci5VqR18cCb=hgnbFKXwy2QPkxo=pw@mail.gmail.com>
Subject: Re: [PATCH 0/7] Documentation: gpio: add character device userspace
 API documentation
To: Kent Gibson <warthog618@gmail.com>
Cc: linux-kernel@vger.kernel.org, linux-gpio@vger.kernel.org, 
	linux-doc@vger.kernel.org, brgl@bgdev.pl, linus.walleij@linaro.org, 
	andy@kernel.org, corbet@lwn.net
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Tue, Jan 9, 2024 at 4:00=E2=80=AFPM Kent Gibson <warthog618@gmail.com> w=
rote:
>
> 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?

--=20
With Best Regards,
Andy Shevchenko