From 38152d71aa0fc1167313723ec190b65421324472 Mon Sep 17 00:00:00 2001
From: Philip Withnall <withnall@endlessm.com>
Date: Wed, 6 Dec 2017 12:53:10 +0000
Subject: [PATCH] lib/repo: Clarify documentation for
 ostree_repo_list_refs{,_ext}()
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Try and clarify what happens with the prefixes, and that they always
return refspecs.

I’m still not 100% sure this is right.

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

Closes: #1347
Approved by: cgwalters
---
 src/libostree/ostree-repo-refs.c | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/src/libostree/ostree-repo-refs.c b/src/libostree/ostree-repo-refs.c
index ed496253..97206cfb 100644
--- a/src/libostree/ostree-repo-refs.c
+++ b/src/libostree/ostree-repo-refs.c
@@ -726,13 +726,17 @@ _ostree_repo_list_refs_internal (OstreeRepo       *self,
  * @self: Repo
  * @refspec_prefix: (allow-none): Only list refs which match this prefix
  * @out_all_refs: (out) (element-type utf8 utf8) (transfer container):
- *    Mapping from ref to checksum
+ *    Mapping from refspec to checksum
  * @cancellable: Cancellable
  * @error: Error
  *
  * If @refspec_prefix is %NULL, list all local and remote refspecs,
  * with their current values in @out_all_refs.  Otherwise, only list
  * refspecs which have @refspec_prefix as a prefix.
+ *
+ * @out_all_refs will be returned as a mapping from refspecs (including the
+ * remote name) to checksums. If @refspec_prefix is non-%NULL, it will be
+ * removed as a prefix from the hash table keys.
  */
 gboolean
 ostree_repo_list_refs (OstreeRepo       *self,
@@ -752,16 +756,18 @@ ostree_repo_list_refs (OstreeRepo       *self,
  * @self: Repo
  * @refspec_prefix: (allow-none): Only list refs which match this prefix
  * @out_all_refs: (out) (element-type utf8 utf8) (transfer container):
- *    Mapping from ref to checksum
+ *    Mapping from refspec to checksum
  * @flags: Options controlling listing behavior
  * @cancellable: Cancellable
  * @error: Error
  *
  * If @refspec_prefix is %NULL, list all local and remote refspecs,
  * with their current values in @out_all_refs.  Otherwise, only list
- * refspecs which have @refspec_prefix as a prefix.  Differently from
- * ostree_repo_list_refs(), the prefix will not be removed from the ref
- * name.
+ * refspecs which have @refspec_prefix as a prefix.
+ *
+ * @out_all_refs will be returned as a mapping from refspecs (including the
+ * remote name) to checksums. Differently from ostree_repo_list_refs(), the
+ * @refspec_prefix will not be removed from the refspecs in the hash table.
  */
 gboolean
 ostree_repo_list_refs_ext (OstreeRepo                 *self,