The (optional) annotation causes a warning because the parameter is not marked as (out). Additionally, the annotations have no effect on the generated documentation.
When a function takes GError **error, then the GObject introspection data includes throws="1".

When gi-docgen sees that annotation, it inserts a standard text about it, so what we write there doesn't matter too much. It will only be seen by people reading the header file directly, so I have inserted a consistent text in those places.

Compiled and saw fewer warnings from gobject-introspection.