Remove gtk-docisms, apply more gi-docgen syntax, and reword things
to be closer to the style recommended in

https://developer.gnome.org/documentation/guidelines/devel-docs.html