USE=doc has a very overloaded meaning.
Meson doesn't ship pre-generated gtk-docs like autotools did, thus
developers writing GLib/GTK+ apps may want to keep them around, as
libraries move from autotools to meson. gtk-doc is integrated into
various IDEs and standalone devhelp viewer, giving a concrete case when
one might want to globally enable this (if using those IDEs until they
don't have online gtk-doc support that's still in the works, offline
developer docs, or matching system versions docs on purpose).
Per-package USE=doc is rather inconvenient to manage.

Suggested description for global gtk-doc USE:
Build and install gtk-doc based developer documentation

Longer version idea:
Build and install gtk-doc based developer documentation for dev-
util/devhelp, IDE and offline use


As the "Build" in the description suggests, this is only for when a
generation is needed. In practice this means that it shouldn't be used
for autotools based builds from tarballs, where the gtk-doc is already
shipped - for those you just want a dev-util/gtk-doc-am build dep,
which will make gtkdoc-rebase available that the standard gtk-doc
autotools rules call to make the pre-generated docs pretty much equal
to what you'd get from regenerating (mainly local offline links). In
those aforementioned autotools cases, it's often questionable to have a
USE flag (doc) at all for this when using proper tarballs.

Most GNOME libraries have converted to using meson, thus building them
is necessary to keep local developer docs available and thus keep IDE
integration useful. Just always building gtk-doc would be distasteful
to some, hence this global USE flag proposal. There will be dozens of
consumers as I bump libraries for GNOME 3.26 and even more so 3.28 and
3.30 soon enough afterwards. Some are already there (including some not
from GNOME), which currently use USE=doc for this.
Instead of supporting disted tarballs with meson, they plan to do
aforementioned online docs support for the API docs integrations, but
I haven't heard about any progress on that, plus offline use use case
will remain anyways.


Mart