On Mon, Jun 2, 2025 at 7:16 AM Daniel P. Berrangé <berra...@redhat.com> wrote:
> 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. > I'm assuming here that you are opposing the "by module" categorization specifically. Fair enough. Markus has said similar things; that the split by module is more of a sin of necessity than a genuine categorization. I suppose in my mind's eye it is my hope that they WOULD be useful for grouping like commands, structures, and events by topic. I admit they are not necessarily strictly adherent to that idea at the moment. However, I think it's *conceptually* useful to group together, say, "block related things" into a block topic. Modules may not fit this 1:1 at current, but it's the best we have. If there's opposition to doing it in this manner, I cede, but still maintain that grouping things by topic would be superior to a flat list of just absolutely everything. > > 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. > Keep in mind that once the "inliner" is merged, the great majority of "internal" structures will be omitted from this index. The exact definition of what is elided is hard for me to describe formally, but: Any object that is currently referenced only via "...The members of ..." will be omitted, as the information relating to that definition will be inlined into the appropriate command/event instead. This will also by definition exclude entities that aren't referenced at all, such as internal definitions we use for QOM/QDEV and similar purposes. Due to a limitation in how I present alternates (i.e. via reference to the type and not by inlining the choices/types), alternates are one of the few types whose internal details remain even after the inliner is merged. This isn't a fundamental barrier, just where the cutting room knife made the excision, and can be remedied in the future. The algorithm for what is visible is something like the following: 1. All entities are hidden by default. 2. All commands and events are marked visible. 3. All member types belonging to a visible entity (commands, events) are marked as visible; i.e. if an event uses an enum or a command takes a compound object as an argument, those entities become visible in the documentation, even though the name of that type is an "internal detail". This is because I do not have a system in place for presenting recursive structures, and it is currently easiest to link to these types by reference, necessitating their visibility. This marking is carried out recursively. 4. All return types, currently, are marked visible. In the future we may inline return structures in a manner similar to members, but we do not do so, yet. This isn't enough to remove *all* internal types, but it does get a lion's share of them and thins the documentation considerably. I don't have numbers on hand at present, but when I get these prerequisite series out of the way, I can enumerate them. > > 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. > Yes; but that's how indices are at times: multiple things are listed in multiple places to facilitate lookup. It is not really meant to be space efficient. In my case, the things I really truly care about are: (1) A true alphabetical list of all symbols we have documented, and (2) A list of all events and commands, specifically. Everything else more or less just comes along for the ride by parallel; making an index for events/commands inherently creates an index for objects, enums, etc. I didn't see a need to specifically exclude them. > > 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. > That'd be cool! Unfortunately I'm going to reply here with the dreaded "patches welcome". I'm worried I don't have the mandate to spend much more time on this project than I already have... :( If you'd like to take a crack at it, I would be happy to advise. > > > > 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 ? > Maybe! This patchset is one of those cases where I went to fix one thing and got carried away... If I can extract just this fix by its lonesome I will do so. I admit that I forget right now how easy that is to do, or if it relies on my restructuring of other elements. ... It's probably easy enough to rewrite, anyway. > > > 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. > I suppose so. If we do not find the master index useful, we could go the other route and eliminate it entirely, leaving only the domain-specific indices. I recall Markus at one point assumed the master index to work as this patch makes it work, so I just closed the loop here. The way it currently actually works is that the master index only indexes items that have no associated domain, which turns out to be essentially nothing. > > > 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 :| > >
