lib/core: Expand documentation for ostree_parse_refspec()
lib/core: Expand documentation for ostree_parse_refspec()

The old documentation had outdated and incomplete annotations, and
didn’t make it very clear that out_remote could legitimately return
NULL.

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

Closes: #1437
Approved by: cgwalters

GNOME/ostree,GNOME/ostree,GNOME/ostree,GNOME/ostree,GNOME/ostree