From 785da8d5a632b12f94c93e78f2751c14e6a777ba Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 29 Jan 2018 14:14:29 +0000 Subject: [PATCH] lib/core: Expand documentation for ostree_parse_refspec() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Closes: #1437 Approved by: cgwalters --- src/libostree/ostree-core.c | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/src/libostree/ostree-core.c b/src/libostree/ostree-core.c index 2256a2c0..2f633dcb 100644 --- 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,