Cleanup gir annoatiotions, improve docs, fix some links and make gir and doc build warnings fatal
Documentation is still very scarce for a library but let's at least raise the bar a bit by requiring introspection build and doc build to fail without warnings. Add some docstrings while at that.