[Cogl] Documentation fixes

[Damien Lespiau]

Hey!

The following series fixes most if not all easily fixable issues when
generating our gtk-doc reference manual. It makes our amount of warnings go
from ~330 to ~30 and add a lot of previously hidden, but written, sections to
the documentation.

Almost no editorial change has been done, that's reserved for other times.

Another worthy goal is to reach 100% of the public symbols documented,
hopefully within reach with this cleanup.

I've also added unrelated changes that I spotted while skimming through the
code as a result of the documentation fixes. All quite trivial.

HTH,

--
Damien