Re: [PATCH 1/1] docs/qapi-domain: Improve QAPI indices

["Daniel P. Berrangé" <berrange@redhat.com>]

On Fri, May 23, 2025 at 02:08:09PM -0400, John Snow wrote:
> This patch changes the "by type" categorization in favor of using
> sub-categories of a literal "By type" category instead. A new "By
> module" categorization is also added that follows a similar pattern.

I'm not much of a fan of this. IMHO unless you are looking at the
module(s) for the subsystem you are the maintainer of, the split
of definitions across modules comes across as somewhat arbitrary
and unpredictable.

Looking at this from the POV of a consumer of QMP, our entrypoint
to research is either a command name or an event name.

The data type names of enums/alternates/objects are an internal
QEMU detail that's not part of the public API.

If we consider the index currently:

  Alternates | Commands | Enums | Events | Modules | Objects | A | .... | Z

The A ... Z bits link to a mix of all type names, which is a bit
overwhealming.

At the same time the page is twice as big as it needs to be
as the same info is repeated under the A-Z index and the
other per-type indexes.

I think what would help would be to make the index dynamic

eg

  A | B | C | D | E | ... | X | Y | Z

  [ ] Show internal types 

The A-Z index would default to showing commands and events.
Selecting the "Types" checkbox would toggle display of the
alternate/enum/object names, which could be done via having
a CSS class on each index entry, and javascript which just
toggles 'display: none' / 'display: block' CSS property on
the elements with the given class. I'm not convinced we need
the modules in the index.


> Alphabetical sorting has been improved and will sort in a case
> insensitive manner for all categories, now.

This is trivial and nice and could be a standalone fix ?

> Lastly, the "main" QAPI Index (qapi-index.html) is altered to index
> *everything* from all namespaces, adding disambiguation where necessary
> to do so.

This looks a bit wierd having the same types and modules repeated
multiple times.


With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|