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

diff --git a/src/libostree/ostree-core.c b/src/libostree/ostree-core.c
index 2256a2c063b9c4d6a43d512adee1a239aa55ba19..2f633dcb7cb4c6f587385a700c9cec1579663e46 100644 (file)
--- a/src/libostree/ostree-core.c
+++ b/src/libostree/ostree-core.c
@@ -152,15 +152,18 @@ ostree_validate_checksum_string (const char *sha256,
 /**
  * ostree_parse_refspec:
  * @refspec: A "refspec" string
- * @out_remote: (out) (allow-none): The remote name, or %NULL if the refspec refs to a local ref
- * @out_ref: (out) (allow-none): Name of ref
+ * @out_remote: (out) (nullable) (optional): Return location for the remote name,
+ *    or %NULL if the refspec refs to a local ref
+ * @out_ref: (out) (not nullable) (optional): Return location for the ref name
  * @error: Error
  *
- * Split a refspec like "gnome-ostree:gnome-ostree/buildmaster" into
- * two parts; @out_remote will be set to "gnome-ostree", and @out_ref
- * will be "gnome-ostree/buildmaster".
+ * Split a refspec like `gnome-ostree:gnome-ostree/buildmaster` or just
+ * `gnome-ostree/buildmaster` into two parts. In the first case, @out_remote
+ * will be set to `gnome-ostree`, and @out_ref to `gnome-ostree/buildmaster`.
+ * In the second case (a local ref), @out_remote will be %NULL, and @out_ref
+ * will be `gnome-ostree/buildmaster`. In both cases, %TRUE will be returned.
  *
- * If @refspec refers to a local ref, @out_remote will be %NULL.
+ * Returns: %TRUE on successful parsing, %FALSE otherwise
  */
 gboolean
 ostree_parse_refspec (const char   *refspec,