Gi-docgen: Organizing documentation contents

Platform
, , ,
1

Each documentation tree generated by gi-docgen has a landing/index page based on a common template, and following a familiar pattern like the one for Gio. The outline is something like this, though not every section will appear in every doc:

(general library metadata)

Build

Dependencies

Related libraries

Additional documentation

(static documentation pages usually written in MarkDown)

Classes

Interfaces

Structs

Aliases

Enumeration

Bitfields

Error Domains

Callbacks

Functions

Function Macros

It’s the “table of contents” part of the outline, from Classes on down, that I’m focusing on at the moment.

I’m curious how useful other people find it, to have the various member lists divided into those categories. Is it vital to anyone’s documentation needs that they be able to see a list of all of the enums in Gio, or every callback defined in the library? Do people go looking for a listing of all the members of a category, and only the members of that category?

To some extent it feels like the categories are there sort of arbitrarily, simply to give the list some structure and avoid dumping out every name as one huge alphabetical list. But often, one big alphabetical list is actually closer to what I’m looking for, and the symbol-type categories just get in the way.

In the Gtk docs, much of what people would go looking for is in the Classes list. Nearly(?) every widget is a Class. But Gio is a good example because a lot of things you’d go looking for are in Classes, but a lot of other things you’d go looking for are in Interfaces.

  • Gio.FileInfo is a Class, but Gio.File is an Interface.
  • Gio.FileIcon is a Class, but Gio.Icon is an Interface.
  • Gio.Mount, Gio.Drive, and Gio.Volume are all Interfaces.
  • Gio.Cancellable is a Class. Gio.Seekable is an Interface.
  • Gio.{Menu, MenuItem}: both Classes.
  • So is Gio.MenuModel. And the Gio.DBusMenuModel derived from it. But Gio.ListModel is an Interface.
  • Gio.{Action, ActionGroup, ActionMap}: all Interfaces. But Gio.ActionEntry? …Tricked you, that’s a Struct.

You get the idea.

So the effect this has, in practice, is that when I go to look up the docs for some part of Gio, I often end up checking several lists to find it. I’ll nearly always start in Classes, but it’s often not there so I have to check Interfaces. If I still don’t find it, keep going down the list(s).

Yes, of course I could just use the search box. I should use the search box. But I often don’t, for reasons both valid and in-, and when I don’t it feels like the categories just make information harder to locate.

The categories are also why documentation for these is scattered throughout the page:

File, FileAttributeInfo, FileAttributeInfoList, FileAttributeMatcher, FileAttributeStatus, FileAttributeType, FileCopyFlags, FileCreateFlags, FileEnumerator, FileIcon, FileInfo, FileInputStream, FileIOStream, FileMeasureFlags, FileMeasureProgressCallback, FileMonitorEvent, FileMonitorFlags, FileOutputStream, FileQueryInfoFlags, FileMeasureProgressCallback, FileProgressCallback, FileReadMoreCallback, FileType

In a simple alphabetical list, they’d all be right next to each other.

I’m not saying that the listings couldn’t benefit from some sort of additional structure, whether organized around topic, or goals, or what have you.

But I am saying that just having Gio.File, Gio.FileInfo, Gio.FileInfoFlags, and GioFileType listed in close proximity seems a lot more useful than a (set of) list(s) where Gio.FileType is immediately followed by Gio.IOModuleScopeFlags and Gio.MemoryMonitorWarningLevel.

1 Like