[ostree] libostree: Extend gtk-doc coverage for refs and prune APIs

[Colin Walters <walters src gnome org>]

commit 871be4b75af16ccec86c35d6dc8cdfb838889dc8
Author: Colin Walters <walters verbum org>
Date:   Mon Aug 19 10:16:05 2013 -0400

    libostree: Extend gtk-doc coverage for refs and prune APIs

 src/libostree/ostree-repo-prune.c |   37 ++++++++++++++++++++----
 src/libostree/ostree-repo-refs.c  |   57 ++++++++++++++++++++++++++++++------
 src/libostree/ostree-repo.h       |    4 +-
 3 files changed, 80 insertions(+), 18 deletions(-)
---
diff --git a/src/libostree/ostree-repo-prune.c b/src/libostree/ostree-repo-prune.c
index a64b1c3..f042902 100644
--- a/src/libostree/ostree-repo-prune.c
+++ b/src/libostree/ostree-repo-prune.c
@@ -87,8 +87,33 @@ maybe_prune_loose_object (OtPruneData        *data,
   return ret;
 }
 
+/**
+ * ostree_repo_prune:
+ * @self: Repo
+ * @flags: Options controlling prune process
+ * @depth: Stop traversal after this many iterations (-1 for unlimited)
+ * @out_objects_total: (out): Number of objects found
+ * @out_objects_pruned: (out): Number of objects deleted
+ * @out_pruned_object_size_total: (out): Storage size in bytes of objects deleted
+ * @cancellable: Cancellable
+ * @error: Error
+ *
+ * Delete content from the repository.  By default, this function will
+ * only delete "orphaned" objects not referred to by any commit.  This
+ * can happen during a local commit operation, when we have written
+ * content objects but not saved the commit referencing them.
+ *
+ * However, if %OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY is provided, instead
+ * of traversing all commits, only refs will be used.  Particularly
+ * when combined with @depth, this is a convenient way to delete
+ * history from the repository.
+ * 
+ * Use the %OSTREE_REPO_PRUNE_FLAGS_NO_PRUNE to just determine
+ * statistics on objects that would be deleted, without actually
+ * deleting them.
+ */
 gboolean
-ostree_repo_prune (OstreeRepo        *repo,
+ostree_repo_prune (OstreeRepo        *self,
                    OstreeRepoPruneFlags   flags,
                    gint               depth,
                    gint              *out_objects_total,
@@ -106,12 +131,12 @@ ostree_repo_prune (OstreeRepo        *repo,
   OtPruneData data = { 0, };
   gboolean refs_only = flags & OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY;
 
-  data.repo = repo;
+  data.repo = self;
   data.reachable = ostree_repo_traverse_new_reachable ();
 
   if (refs_only)
     {
-      if (!ostree_repo_list_refs (repo, NULL, &all_refs,
+      if (!ostree_repo_list_refs (self, NULL, &all_refs,
                                   cancellable, error))
         goto out;
       
@@ -121,13 +146,13 @@ ostree_repo_prune (OstreeRepo        *repo,
         {
           const char *checksum = value;
           
-          if (!ostree_repo_traverse_commit (repo, checksum, depth, data.reachable,
+          if (!ostree_repo_traverse_commit (self, checksum, depth, data.reachable,
                                             cancellable, error))
             goto out;
         }
     }
 
-  if (!ostree_repo_list_objects (repo, OSTREE_REPO_LIST_OBJECTS_ALL, &objects,
+  if (!ostree_repo_list_objects (self, OSTREE_REPO_LIST_OBJECTS_ALL, &objects,
                                  cancellable, error))
     goto out;
 
@@ -145,7 +170,7 @@ ostree_repo_prune (OstreeRepo        *repo,
           if (objtype != OSTREE_OBJECT_TYPE_COMMIT)
             continue;
           
-          if (!ostree_repo_traverse_commit (repo, checksum, depth, data.reachable,
+          if (!ostree_repo_traverse_commit (self, checksum, depth, data.reachable,
                                             cancellable, error))
             goto out;
         }
diff --git a/src/libostree/ostree-repo-refs.c b/src/libostree/ostree-repo-refs.c
index 9387855..beb481e 100644
--- a/src/libostree/ostree-repo-refs.c
+++ b/src/libostree/ostree-repo-refs.c
@@ -1,6 +1,6 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*-
  *
- * Copyright (C) 2011 Colin Walters <walters verbum org>
+ * Copyright (C) 2011,2013 Colin Walters <walters verbum org>
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -16,8 +16,6 @@
  * License along with this library; if not, write to the
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  * Boston, MA 02111-1307, USA.
- *
- * Author: Colin Walters <walters verbum org>
  */
 
 #include "config.h"
@@ -473,8 +471,20 @@ enumerate_refs_recurse (OstreeRepo    *repo,
   return ret;
 }
 
+/**
+ * ostree_repo_list_refs:
+ * @self: Repo
+ * @refspec_prefix: (allow-none): Only list refs which match this prefix
+ * @out_all_refs: (out) (element-type utf8 utf8): Mapping from ref 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.
+ */
 gboolean
-ostree_repo_list_refs (OstreeRepo       *repo,
+ostree_repo_list_refs (OstreeRepo       *self,
                        const char       *refspec_prefix,
                        GHashTable      **out_all_refs,
                        GCancellable     *cancellable,
@@ -497,9 +507,9 @@ ostree_repo_list_refs (OstreeRepo       *repo,
         goto out;
 
       if (remote)
-        dir = g_file_get_child (repo->remote_heads_dir, remote);
+        dir = g_file_get_child (self->remote_heads_dir, remote);
       else
-        dir = g_object_ref (repo->local_heads_dir);
+        dir = g_object_ref (self->local_heads_dir);
 
       child = g_file_resolve_relative_path (dir, ref_prefix);
       if (!ot_gfile_query_info_allow_noent (child, OSTREE_GIO_FAST_QUERYINFO, 0,
@@ -510,7 +520,7 @@ ostree_repo_list_refs (OstreeRepo       *repo,
         {
           if (g_file_info_get_file_type (info) == G_FILE_TYPE_DIRECTORY)
             {
-              if (!enumerate_refs_recurse (repo, remote, child, child,
+              if (!enumerate_refs_recurse (self, remote, child, child,
                                            ret_all_refs,
                                            cancellable, error))
                 goto out;
@@ -527,12 +537,12 @@ ostree_repo_list_refs (OstreeRepo       *repo,
     {
       gs_unref_object GFileEnumerator *remote_enumerator = NULL;
 
-      if (!enumerate_refs_recurse (repo, NULL, repo->local_heads_dir, repo->local_heads_dir,
+      if (!enumerate_refs_recurse (self, NULL, self->local_heads_dir, self->local_heads_dir,
                                    ret_all_refs,
                                    cancellable, error))
         goto out;
 
-      remote_enumerator = g_file_enumerate_children (repo->remote_heads_dir, OSTREE_GIO_FAST_QUERYINFO,
+      remote_enumerator = g_file_enumerate_children (self->remote_heads_dir, OSTREE_GIO_FAST_QUERYINFO,
                                                      0,
                                                      cancellable, error);
 
@@ -549,7 +559,7 @@ ostree_repo_list_refs (OstreeRepo       *repo,
             break;
 
           name = g_file_info_get_name (info);
-          if (!enumerate_refs_recurse (repo, name, child, child,
+          if (!enumerate_refs_recurse (self, name, child, child,
                                        ret_all_refs,
                                        cancellable, error))
             goto out;
@@ -606,6 +616,23 @@ write_ref_summary (OstreeRepo      *self,
   return ret;
 }
 
+/**
+ * ostree_repo_write_ref:
+ * @self: Repo
+ * @remote: (allow-none): Optional remote name
+ * @name: Name of ref, e.g. foo/bar/baz
+ * @rev: (allow-none); ASCII SHA256 checksum; if %NULL, then delete @name
+ * @error: Error
+ *
+ * If @rev is not %NULL, then it as the target of ref named @name; if
+ * @remote is provided, the ref will appear originate from that
+ * remote.
+ *
+ * Otherwise, if @rev is %NULL, then delete the ref @name if it exists.
+ *
+ * This function merely changes the ref target; it is possible to use
+ * it to target earlier commits.
+ */
 gboolean      
 ostree_repo_write_ref (OstreeRepo  *self,
                        const char  *remote,
@@ -659,6 +686,16 @@ ostree_repo_write_ref (OstreeRepo  *self,
   return ret;
 }
 
+/**
+ * ostree_repo_write_refspec:
+ * @self: Repo
+ * @refspec: Optional remote with name of ref, e.g. remotename:foo/bar/baz
+ * @rev: (allow-none); ASCII SHA256 checksum; if %NULL, then delete @refspec
+ * @error: Error
+ *
+ * Like ostree_repo_write_ref(), but takes concatenated @refspec
+ * format as input instead of separate remote and name arguments.
+ */
 gboolean
 ostree_repo_write_refspec (OstreeRepo  *self,
                            const char  *refspec,
diff --git a/src/libostree/ostree-repo.h b/src/libostree/ostree-repo.h
index 102fbf5..0081b43 100644
--- a/src/libostree/ostree-repo.h
+++ b/src/libostree/ostree-repo.h
@@ -173,7 +173,7 @@ gboolean      ostree_repo_write_refspec (OstreeRepo  *self,
                                          const char  *rev,
                                          GError     **error);
 
-gboolean      ostree_repo_list_refs (OstreeRepo       *repo,
+gboolean      ostree_repo_list_refs (OstreeRepo       *self,
                                      const char       *refspec_prefix,
                                      GHashTable      **out_all_refs,
                                      GCancellable     *cancellable,
@@ -405,7 +405,7 @@ typedef enum {
   OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY
 } OstreeRepoPruneFlags;
 
-gboolean ostree_repo_prune (OstreeRepo        *repo,
+gboolean ostree_repo_prune (OstreeRepo        *self,
                             OstreeRepoPruneFlags   flags,
                             gint               depth,
                             gint              *out_objects_total,