garray: Document that return value of g_ptr_array_remove() may be junk

If using g_ptr_array_remove*() with a non-NULL GDestroyNotify function,
the value returned will probably be freed memory (depending on what the
GDestroyNotify) function actually does. Warn about that in the
documentation. We can’t just unconditionally return NULL in these cases,
though, since the user might have set the GDestroyNotify to a nifty
function which doesn’t actually free the element; so returning it might
still be valid and useful.

Also add missing (nullable) annotations to that documentation.

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

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