Document Gio.File / Gio.FileInfo APIs with practical examples, explanations...
Given their importance/prominence, it's surprising how spare the available, official documentation is for many Gio APIs.
The Gio.File
interface, the associated helper classes like Gio.FileInfo
that implement its features... heck, really just all of Gio. If not the entire Gio documentation, then at least the bulk of it, is nothing but screen after screen of impenetrable function synopses and symbol lists with nothing to tie them together or give the reader any insight into how they should be used. (Let alone why!)
It reads like an autogenerated API doc that really wants you to KNOW it's an autogenerated API doc.
Out of all the core libraries at docs.gtk.org, the Gio docs are the least fleshed out with supplementary discussions, higher-level explanations, or samples of readable, informative code. Other than the generated API reference, there's the one Overview page... and then, that's it.
Well, there is one other set of nno-generated pages: a set of migration guides intended for an audience that no longer exists. Documents like Migrating from GConf to GSettings and Migrating from GnomeVFS to GIO were no doubt invaluable early-on, to get developers familiar with those previous offerings up to speed on the replacement APIs. But by now that job is long since completed, and the audience for those guides is all but extinct.
Looking past the prose, in the entire manual there's exactly one long-form, detailed example. And it:
- Was missing from the docs for over 3.5 years from 2015 - 2019, due to build issues
- Is focused entirely on implementing a DBus interface, nothing else
- Consists of nothing but the relevant XML protocol definitions, plus the
gdbus-codegen
-produced implementation for it... even the lone example includes zero lines of human-written source code!
Last week, I needed to use Gio.File
and friends to modify the filesystem permission bits of a set of disk files. After bashing my head against the Gio documentation for 45 minutes, I gave up trying to find any useful information, went over to the Nautilus source repo, and read its filesystem-facing code to figure out what I needed to do. If I'd stuck with the Gio docs themselves, I'd still be scratching my head trying to dig that information out of them. I'm not sure it's even actually in them at all.
Some grounded explanations, guided tours through Gio's thick forests of API calls, and worked, practical examples based on real-world scenarios are desperately needed.