It is wholly inconsequential, sorry. The fact that you, or others, may not like some aspects of the API reference has to be weighted against a very simple fact: people were not well served by the older reference.
The “let’s dump everything into a single page” works fine for a small API, but becomes absolutely useless when it comes to large code bases like GTK, and GTK is the target for gi-docgen; it gets even worse when we start adding a recursive aspect to a class index: one of the biggest issues with the old gtk-doc reference was that people never understood that type A inherits methods, properties, and signals from it’s parent type P, or from all the interfaces it implements.
Reducing the amount of visual noise in the index allowed adding more useful information; relying on progressive disclosure, with collapsible sections and more information deferred to the per-symbol page, allowed to add things like the type of each argument, including container types; the generated blurb for ownership transfer, nullability, and string format; the links to property accessors and signal emitters.
Another fundamental aspect of the format of the C API reference is that any reader can easily transfer knowledge between C and other languages, which is something that happens every day in the GNOME platform.
Gi-docgen is the result of nearly 20 years of feedback against gtk-doc, from experts to newcomers, as well as looking at what everybody else does in the documentation space; I don’t expect its output to be liked by everybody, but the choices I made where not based on whims—though I also feel no real compunction to justify them to everybody, because at the end of the day, I’m the person that put in the work to make this thing happen, and that maintains it.
I mentioned very specific aspects. All the improvements that led to gi-docgen are safe.
I don’t know if people misunderstood the inheritance mechanism in the past, but definitely that is something that can be shown collapsed today (where in the past it was not shown at all, if not for a small tree). But what belongs to a specific subclass has no reason to appear collapsed in the documentation of the very same subclass. This is at least what logic suggests.
The idea of collapsing sections is also usually more used in the output for mobile devices rather than for desktop computers. For instance, Wikipedia might collapse things if you visit it with your phone, but not if you visit with your computer.
Also I am not suggesting to have the whole GTK library in one page, but only the documentation of each section (e.g. GtkText, GtkWidget, etc.). Some of these will be very big pages (e.g. GtkWidget), while some will be smaller pages (e.g. GMenuModel). I guess that is simply natural.
But I guess I have spoken enough for now. Others might want to contribute to this discussion. In the meanwhile I will be silent for a bit.
Sorry, I just checked Gtk.Window and it looks like it already behaves reasonably with everything except the inherited stuff and class structure expanded. That’s probably already the best default.
On the main page Gtk – 4.0 I would consider just expanding everything to make Ctrl+F easier.
I completely agree. In my opinion Gtk.Window should be taken as a model for what can be collapsed and what not. I have no idea why other pages behave differently.
As for data types, I was thinking that, if not in the left menu, they could at least be shown on the right side of the page together with the brief of each function (maybe very very small if you are worried about the space taken). How would that sound?
Do you have any idea how big that makes the page? No, that’s the only place where “collapsed by default” is warranted.
If you go on the sidebar and select a type group (classes, enumerations, etc), you’ll get to the corresponding section, and it will be automatically expanded for you; you also want to search, at that point. The search in the website uses fuzzy text lookup, and can search across terms and types, so you don’t need to be exact.
They don’t: the same template is used for everything.
My two cents: sometimes I use valadoc because the format is, in my opinion, better. Although also, as time goes by, I’ve been getting used to the new documentation and currently I prefer it over the old format.
I am not sure what you mean here to compare to a random wikipedia page. This is not a very representative sample of wikipedia either, as it is in the top 0.005% of largest pages on the whole English wiki.
(Their guidelines actually recommend splitting or trimming pages that are that large, most other pages of that size have a notice about how the article is too long but for some reason that one does not)
True. But that would be also the case of Gtk – 4.0, which is probably the largest page of the entire documentation. The average page in the case of GTK would probably be something like GtkAlertDialog.
By the way, the latter has the sections correctly expanded, but it would not lose too much functionality if it didn’t, because the content of each section is repeated in the left menu. In the case of Gtk – 4.0 instead, for having an overview there is no other way than expanding each section one by one every time the page is loaded.
Again, this comes from my personal experience with the documentation of libadwaita (for GTK I still rely on the old website). While I was still learning about libadwaita I did not remember how the various widgets were called, so I would simply go to the main page and read. At some point though the sections became collapsed, so I had to go to the main page and open each section by hand every time. Things get even worse if you, curious about a widget, click on it: the widget was not what you were looking for, and now that you have gone back, the section that you were reading has gone back to collapsed state.
Sorry I cannot reproduce this, when I click on something from the index and then press the back button, the sections are still expanded. Maybe you have too many tabs open in the browser and the cache is getting evicted?
You are right, imprecision from my side. If you use the “back” button the sections are still open. But sometimes you might click on a widget, then click on a function, then click on the data type of one of its arguments, and so on. At that point for going back it is more convenient to click on the “ADW” button on the left menu rather than clicking “back” a thousand times. In that case the sections are again in collapsed state.
BTW, the documentation that is locally installed by Linux distributions (at least, by Debian-based ones) still uses GTK-Doc. I hope that this will be kept unchanged.
Unless GtkDoc goes back to “maintained” state, and furthermore starts adapting to all the improvements that are regularly added to gi-docgen, the most likely scenario is that it will be abandoned at some point.
References generated by gi-docgen are already installed under /usr/share/doc for most libraries, and tools like Biblioteca exist to read them; gi-docgen also generates a DevHelp index file, but DevHelp is on its way out as well, as it’s overengineered and hard to port to GTK4 and libadwaita.
I was searching for ways to do UTF8 case folding using GLib, so I googled it. Google threw me this page: GLib.str_tokenize_and_fold. Wrong result: I am fine with folding, but I don’t need to tokenize. So I would like to go “up” to the parent page and search for another function.
With the old documentation it was very simple, because the same function was in the String Utility Functions page together with similar functions. But now? How can I go “up” and see the “sister functions” of GLib.str_tokenize_and_fold?
If I did not know about “String Utility Functions” from the old documentation, by simply visiting GLib.str_tokenize_and_fold I would not know in which part of the documentation I am.
Many parts of the documentation have the identical problem.
