This will fix a few broken links in the documentation, and shut up a
load of gtk-doc warnings (but certainly not all of them).

Signed-off-by: Philip Withnall <withnall@endlessm.com>

https://bugzilla.gnome.org/show_bug.cgi?id=790015

Sub-directories inside gio/ already processed in a previous commit:
- fam/
- gdbus-2.0/ (which contains only codegen/)
- gvdb/
- inotify/
- tests/
- win32/
- xdgmime/

Other sub-directories inside gio/:
- completion/: no license headers
- kqueue/: not LGPL, BSD-style license

https://bugzilla.gnome.org/show_bug.cgi?id=776504

It's unnecessary, and only adds visual noise; we have been fairly
inconsistent in the past, but the semi-colon-less version clearly
dominates in the code base.

https://bugzilla.gnome.org/show_bug.cgi?id=669355

Being able to determine that a certificate chain is invalid is not
considered an error, but success. This might not be obvious at first
due to the way the method is named and described currently. Since we
cannot change the name, let's improve the description and clarify this
aspect of its behaviour.

https://bugzilla.gnome.org/show_bug.cgi?id=780310

If we have an input parameter (or return value) we need to use (nullable).
However, if it is an (inout) or (out) parameter, (optional) is sufficient.

It looks like (nullable) could be used for everything according to the
Annotation documentation, but (optional) is more specific.

This makes them easier to identify when debugging and profiling.

This patch was somewhat less than interesting to write.

https://bugzilla.gnome.org/show_bug.cgi?id=767765

https://bugzilla.gnome.org/show_bug.cgi?id=750573

https://bugzilla.gnome.org/show_bug.cgi?id=730493

Instead of "Return value:".