Improve formatting while I’m there, and try and ensure all the docs in
these two files matches the
[guidelines](https://developer.gnome.org/documentation/guidelines/devel-docs.html#writing-api-references

).

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3250