> But GTK-doc¹ themselves say on the main page that their tool might be a bit awkward to use, and recommend doxygen instead.
But once it's setup, the chapters are better delineated, the layout is better, and it's overall easier to read.
> Also, the only difference I see in "before" and "after" links to documentation is a number of chapters, which could've been added in doxygen too.
You came in too late, all the documentation on the site is now generated with gtk-doc. This is what the old API docs looked like: http://www.reactivated.net/fprint/api/
22 October 2018 at 13:33
Fingerprint readers are more and more common on Windows laptops, and hardware makers would really like to not have to make a separate SKU without the fingerprint reader just for Linux, if that fingerprint reader is unsupported there.
The original makers of those fingerprint readers just need to send patches to the libfprint Bugzilla, I hear you say, and the problem's solved!
But it turns out it's pretty difficult to write those new drivers, and those patches, without an insight on how the internals of libfprint work, and what all those internal, undocumented APIs mean.
Most of the drivers already present in libfprint are the results of reverse engineering, which means that none of them is a best-of-breed example of a driver, with all the unknown values and magic numbers.
Let's try to fix all this!
Step 1: fail faster
When you're writing a driver, the last thing you want is to have to wait for your compilation to fail. We ported libfprint to meson and shaved off a significant amount of time from a successful compilation. We also reduced the number of places where new drivers need to be declared to be added to the compilation.
Step 2: make it clearer
While doxygen is nice because it requires very little scaffolding to generate API documentation, the output is also not up to the level we expect. We ported the documentation to gtk-doc, which has a more readable page layout, easy support for cross-references, and gives us more control over how introductory paragraphs are laid out. See the before and after for yourselves.
Step 3: fail elsewhere
You created your patch locally, tested it out, and it's ready to go! But you don't know about git-bz, and you ended up attaching a patch file which you uploaded. Except you uploaded the wrong patch. Or the patch with the right name but from the wrong directory. Or you know git-bz but used the wrong commit id and uploaded another unrelated patch. This is all a bit too much.
We migrated our bugs and repository for both libfprint and fprintd to Freedesktop.org's GitLab. Merge Requests are automatically built, discussions are easier to follow!
Step 4: show it to me
Now that we have spiffy documentation, unified bug, patches and sources under one roof, we need to modernise our website. We used GitLab's CI/CD integration to generate our website from sources, including creating API documentation and listing supported devices from git master, to reduce the need to search the sources for that information.
Step 5: simplify
This process has started, but isn't finished yet. We're slowly splitting up the internal API between "internal internal" (what the library uses to work internally) and "internal for drivers" which we eventually hope to document to make writing drivers easier. This is partially done, but will need a lot more work in the coming months.
TL;DR: We migrated libfprint to meson, gtk-doc, GitLab, added a CI, and are writing docs for driver authors, everything's on the website!
"Fingerprint reader support, the second coming"
3 Comments -
This is great work, Bastien! So many improvements in so many areas. Thanks for all of your work!
13 June 2018 at 14:45
But GTK-doc¹ themselves say on the main page that their tool might be a bit awkward to use, and recommend doxygen instead.
Also, the only difference I see in "before" and "after" links to documentation is a number of chapters, which could've been added in doxygen too.
1: https://www.gtk.org/gtk-doc/
22 October 2018 at 13:15
> But GTK-doc¹ themselves say on the main page that their tool might be a bit awkward to use, and recommend doxygen instead.
But once it's setup, the chapters are better delineated, the layout is better, and it's overall easier to read.
> Also, the only difference I see in "before" and "after" links to documentation is a number of chapters, which could've been added in doxygen too.
You came in too late, all the documentation on the site is now generated with gtk-doc. This is what the old API docs looked like:
http://www.reactivated.net/fprint/api/
22 October 2018 at 13:33