Strawman: Adapt documentation to gi-docgen
GTK, Pango, and GdkPixbuf have moved away from gtk-doc to gi-docgen, a documentation generator that is strictly based on introspection data. The advantages of gi-docgen are various:
- real Markdown
- explicit documentation annotations instead of automagic gtk-doc sigils
- minimal dependencies
- fast documentation build times
- auto-generation of documentation fragments based on introspection annotations, like
nullable
,array
,transfer
, etc. - API reference matching 1:1 with what bindings developers experience
- client side search
- client side cross-references
Of course, as GLib cannot generate introspection data because of the cyclic dependency on gobject-introspection, we cannot simply drop gtk-doc and move to gi-docgen. Nevertheless, there are some things we can do to the GLib documentation to make it render better with gi-docgen until such time when we can use it in tree—namely:
- ensure that every gtk-doc stanza starts with a single paragraph description of function/macro/property/signal; gi-docgen uses the first paragraph as the summary inside indices
- ensure that every
SECTION
gtk-doc stanza that refers to a type has the name of the type as the section name; e.g.GConverter
should have aSECTION:gconverter
,GActionGroup
should have aSECTION:gactiongroup
, etc. - ensure that every type that does not have a matching
SECTION
has a full description; e.g.GZlibDecompressor
should have a description that is more verbose thanZlib decompression
; or its section should be renamed fromSECTION:gzdecompressor
toSECTION:gzlibdecompressor
If we ever decide to switch to gi-docgen from gtk-doc we're going to have to do some more work:
- replace gtk-doc
#
sigils with explicit links, e.g.#GArray
becomes[struct@GLib.Array]
,#GInitiallyUnowned
becomes[class@GObject.InitiallyUnowned]
- replace gtk-doc
%
sigils with plain Markdown code fragments - replace gtk-doc
()
function auto-linking with explicit links, like[ctor@GObject.Object.new]
,[func@GLib.strdup]
,[method@Gio.DBusConnection.get_unique_name]
- remove
SECTION
stanzas and move complex descriptions either into the type description or into a separate Markdown file
Most of the changes above are quite invasive, and while they make the reference more useful, they are also the most time consuming and require a certain level of commitment to a new documentation tool.
Before attempting the first, non-invasive set of changes, I'd like to gauge the buy-in from the GLib developers.