libostree: Add gtk-doc section for ostree-repo.c

5 files changed, 163 insertions, 17 deletions

diff --git a/doc/ostree-docs.xml b/doc/ostree-docs.xml
index 71561acc..33936555 100644
--- a/doc/ostree-docs.xml
+++ b/doc/ostree-docs.xml
@@ -16,6 +16,7 @@
 	<chapter xml:id="reference">
 		<title>API Reference</title>
 		<xi:include href="xml/libostree-core.xml"/>
+		<xi:include href="xml/libostree-repo.xml"/>
 
 		<index id="api-index-full">
 			<title>API Index</title>
diff --git a/doc/ostree-sections.txt b/doc/ostree-sections.txt
index 9d293fa1..98f1d033 100644
--- a/doc/ostree-sections.txt
+++ b/doc/ostree-sections.txt
@@ -61,3 +61,67 @@ ostree_validate_structureof_dirtree
 ostree_validate_structureof_dirmeta
 ostree_commit_get_parent
 </SECTION>
+
+<SECTION>
+<FILE>libostree-repo</FILE>
+OstreeRepoMode
+ostree_repo_new
+ostree_repo_check
+ostree_repo_get_path
+ostree_repo_get_mode
+ostree_repo_mode_from_string
+ostree_repo_get_config
+ostree_repo_copy_config
+ostree_repo_get_parent
+ostree_repo_write_config
+ostree_repo_prepare_transaction
+ostree_repo_commit_transaction
+ostree_repo_commit_transaction_with_stats
+ostree_repo_abort_transaction
+ostree_repo_has_object
+ostree_repo_stage_metadata
+ostree_repo_stage_metadata_async
+ostree_repo_stage_metadata_finish
+ostree_repo_stage_metadata_trusted
+ostree_repo_stage_content
+ostree_repo_stage_content_trusted
+ostree_repo_stage_content_async
+ostree_repo_stage_content_finish
+ostree_repo_resolve_rev
+ostree_repo_write_ref
+ostree_repo_write_refspec
+ostree_repo_list_refs
+ostree_repo_load_variant_c
+ostree_repo_load_variant
+ostree_repo_load_variant_if_exists
+ostree_repo_load_file
+ostree_repo_load_object_stream
+ostree_repo_query_object_storage_size
+ostree_repo_delete_object
+OstreeRepoCommitFilterResult
+OstreeRepoCommitFilter
+OstreeRepoCommitModifier
+ostree_repo_commit_modifier_new
+ostree_repo_commit_modifier_ref
+ostree_repo_commit_modifier_unref
+ostree_repo_stage_directory_to_mtree
+ostree_repo_stage_archive_to_mtree
+ostree_repo_stage_mtree
+ostree_repo_stage_commit
+OstreeRepoCheckoutMode
+OstreeRepoCheckoutOverwriteMode
+ostree_repo_checkout_tree_async
+ostree_repo_checkout_tree_finish
+ostree_repo_checkout_gc
+ostree_repo_read_commit
+OstreeRepoListObjectsFlags
+OSTREE_REPO_LIST_OBJECTS_VARIANT_TYPE
+ostree_repo_list_objects
+ostree_repo_traverse_new_reachable
+ostree_repo_traverse_dirtree
+ostree_repo_traverse_commit
+OstreeRepoPruneFlags
+ostree_repo_prune
+OstreeRepoPullFlags
+ostree_repo_pull
+</SECTION>
diff --git a/src/libostree/ostree-repo-checkout.c b/src/libostree/ostree-repo-checkout.c
index c98cfcf3..f9187ffc 100644
--- a/src/libostree/ostree-repo-checkout.c
+++ b/src/libostree/ostree-repo-checkout.c
@@ -758,6 +758,9 @@ ostree_repo_checkout_tree_finish (OstreeRepo               *self,
 
 /**
  * ostree_repo_checkout_gc:
+ * @self: Repo
+ * @cancellable: Cancellable
+ * @error: Error
  *
  * Call this after finishing a succession of checkout operations; it
  * will delete any currently-unused uncompressed objects from the
diff --git a/src/libostree/ostree-repo.c b/src/libostree/ostree-repo.c
index 4fbd3a53..c7ff2aa4 100644
--- a/src/libostree/ostree-repo.c
+++ b/src/libostree/ostree-repo.c
@@ -36,6 +36,31 @@
 #include "libgsystem.h"
 #include "ostree-repo-file-enumerator.h"
 
+/**
+ * SECTION:libostree-repo
+ * @title: Content-addressed object store
+ * @short_description: A git-like storage system for operating system binaries
+ *
+ * The #OstreeRepo is like git, a content-addressed object store.
+ * Unlike git, it records uid, gid, and extended attributes.
+ *
+ * There are two possible "modes" for an #OstreeRepo;
+ * %OSTREE_REPO_MODE_BARE is very simple - content files are
+ * represented exactly as they are, and checkouts are just hardlinks.
+ * A %OSTREE_REPO_MODE_ARCHIVE_Z2 repository in contrast stores
+ * content files zlib-compressed.  It is suitable for non-root-owned
+ * repositories that can be served via a static HTTP server.
+ *
+ * To store content in the repo, first start a transaction with
+ * ostree_repo_prepare_transaction().  Then create a
+ * #OstreeMutableTree, and apply functions such as
+ * ostree_repo_stage_directory_to_mtree() to traverse a physical
+ * filesystem and stage content, possibly multiple times.
+ * 
+ * Once the #OstreeMutableTree is complete, stage all of its metadata
+ * with ostree_repo_stage_mtree(), and finally create a commit with
+ * ostree_repo_stage_commit().
+ */
 typedef struct {
   GObjectClass parent_class;
 } OstreeRepoClass;
@@ -983,6 +1008,13 @@ ostree_repo_abort_transaction (OstreeRepo     *self,
 
 /**
  * ostree_repo_stage_metadata:
+ * @self: Repo
+ * @objtype: Object type
+ * @expected_checksum: (allow-none): If provided, validate content against this checksum
+ * @object: Metadata
+ * @out_csum: (out) (array fixed-size=32) (allow-none): Binary checksum
+ * @cancellable: Cancellable
+ * @error: Error
  * 
  * Store the metadata object @variant.  Return the checksum
  * as @out_csum.
@@ -992,9 +1024,9 @@ ostree_repo_abort_transaction (OstreeRepo     *self,
  */
 gboolean
 ostree_repo_stage_metadata (OstreeRepo         *self,
-                            OstreeObjectType    type,
+                            OstreeObjectType    objtype,
                             const char         *expected_checksum,
-                            GVariant           *variant,
+                            GVariant           *object,
                             guchar            **out_csum,
                             GCancellable       *cancellable,
                             GError            **error)
@@ -1002,18 +1034,24 @@ ostree_repo_stage_metadata (OstreeRepo         *self,
   gs_unref_object GInputStream *input = NULL;
   gs_unref_variant GVariant *normalized = NULL;
 
-  normalized = g_variant_get_normal_form (variant);
+  normalized = g_variant_get_normal_form (object);
   input = ot_variant_read (normalized);
   
-  return stage_object (self, type, expected_checksum, input, 0, out_csum,
+  return stage_object (self, objtype, expected_checksum, input, 0, out_csum,
                        cancellable, error);
 }
 
 /**
  * ostree_repo_stage_metadata_trusted:
+ * @self: Repo
+ * @objtype: Object type
+ * @checksum: Store object with this ASCII SHA256 checksum
+ * @variant: Metadata object
+ * @cancellable: Cancellable
+ * @error: Error
  * 
- * Store the metadata object @variant; the provided @checksum
- * is trusted.
+ * Store the metadata object @variant; the provided @checksum is
+ * trusted.
  */
 gboolean
 ostree_repo_stage_metadata_trusted (OstreeRepo         *self,
@@ -1075,6 +1113,13 @@ stage_metadata_thread (GSimpleAsyncResult  *res,
 
 /**
  * ostree_repo_stage_metadata_async:
+ * @self: Repo
+ * @objtype: Object type
+ * @expected_checksum: (allow-none): If provided, validate content against this checksum
+ * @object: Metadata
+ * @cancellable: Cancellable
+ * @callback: Invoked when metadata is staged
+ * @user_data: Data for @callback
  * 
  * Asynchronously store the metadata object @variant.  If provided,
  * the checksum @expected_checksum will be verified.
@@ -1181,6 +1226,12 @@ _ostree_repo_get_uncompressed_object_cache_path (OstreeRepo       *self,
 
 /**
  * ostree_repo_stage_content_trusted:
+ * @self: Repo
+ * @checksum: Store content using this ASCII SHA256 checksum
+ * @object_input: Content stream
+ * @length: Length of @object_input
+ * @cancellable: Cancellable
+ * @error: Data for @callback
  *
  * Store the content object streamed as @object_input, with total
  * length @length.  The given @checksum will be treated as trusted.
@@ -1203,6 +1254,13 @@ ostree_repo_stage_content_trusted (OstreeRepo       *self,
 
 /**
  * ostree_repo_stage_content:
+ * @self: Repo
+ * @expected_checksum: (allow-none): If provided, validate content against this checksum
+ * @object_input: Content object stream
+ * @length: Length of @object_input
+ * @out_csum: (out) (array fixed-size=32) (allow-none): Binary checksum
+ * @cancellable: Cancellable
+ * @error: Error
  *
  * Store the content object streamed as @object_input,
  * with total length @length.  The actual checksum will
@@ -1264,15 +1322,22 @@ stage_content_thread (GSimpleAsyncResult  *res,
 
 /**
  * ostree_repo_stage_content_async:
+ * @self: Repo
+ * @expected_checksum: (allow-none): If provided, validate content against this checksum
+ * @object: Input
+ * @length: Length of @object
+ * @cancellable: Cancellable
+ * @callback: Invoked when content is staged
+ * @user_data: User data for @callback
  * 
- * Asynchronously store the content object @object.  If provided,
- * the checksum @expected_checksum will be verified.
+ * Asynchronously store the content object @object.  If provided, the
+ * checksum @expected_checksum will be verified.
  */
 void          
 ostree_repo_stage_content_async (OstreeRepo               *self,
                                  const char               *expected_checksum,
                                  GInputStream             *object,
-                                 guint64                   file_object_length,
+                                 guint64                   length,
                                  GCancellable             *cancellable,
                                  GAsyncReadyCallback       callback,
                                  gpointer                  user_data)
@@ -1283,7 +1348,7 @@ ostree_repo_stage_content_async (OstreeRepo               *self,
   asyncdata->repo = g_object_ref (self);
   asyncdata->expected_checksum = g_strdup (expected_checksum);
   asyncdata->object = g_object_ref (object);
-  asyncdata->file_object_length = file_object_length;
+  asyncdata->file_object_length = length;
   asyncdata->cancellable = cancellable ? g_object_ref (cancellable) : NULL;
 
   asyncdata->result = g_simple_async_result_new ((GObject*) self,
@@ -2268,6 +2333,11 @@ ostree_repo_load_variant_c (OstreeRepo          *self,
 
 /**
  * ostree_repo_load_variant_if_exists:
+ * @self: Repo
+ * @objtype: Object type
+ * @sha256: ASCII checksum
+ * @out_variant: (out) (transfer full): Metadata
+ * @error: Error
  * 
  * Attempt to load the metadata object @sha256 of type @objtype if it
  * exists, storing the result in @out_variant.  If it doesn't exist,
diff --git a/src/libostree/ostree-repo.h b/src/libostree/ostree-repo.h
index e10e672a..69494c99 100644
--- a/src/libostree/ostree-repo.h
+++ b/src/libostree/ostree-repo.h
@@ -41,6 +41,14 @@ gboolean      ostree_repo_check (OstreeRepo  *self, GError **error);
 
 GFile *       ostree_repo_get_path (OstreeRepo  *self);
 
+/**
+ * OstreeRepoMode:
+ * @OSTREE_REPO_MODE_BARE: Files are stored as themselves; can only be written as root
+ * @OSTREE_REPO_MODE_ARCHIVE_Z2: Files are compressed, should be owned by non-root.  Can be served via HTTP
+ *
+ * See the documentation of #OstreeRepo for more information about the
+ * possible modes.
+ */
 typedef enum {
   OSTREE_REPO_MODE_BARE,
   OSTREE_REPO_MODE_ARCHIVE_Z2
@@ -115,8 +123,8 @@ gboolean      ostree_repo_stage_metadata_finish (OstreeRepo        *self,
 
 gboolean      ostree_repo_stage_content (OstreeRepo       *self,
                                          const char       *expected_checksum,
-                                         GInputStream     *content,
-                                         guint64           content_length,
+                                         GInputStream     *object_input,
+                                         guint64           length,
                                          guchar          **out_csum,
                                          GCancellable     *cancellable,
                                          GError          **error);
@@ -124,21 +132,21 @@ gboolean      ostree_repo_stage_content (OstreeRepo       *self,
 gboolean      ostree_repo_stage_metadata_trusted (OstreeRepo        *self,
                                                   OstreeObjectType   objtype,
                                                   const char        *checksum,
-                                                  GVariant          *object,
+                                                  GVariant          *variant,
                                                   GCancellable      *cancellable,
                                                   GError           **error);
 
 gboolean      ostree_repo_stage_content_trusted (OstreeRepo       *self,
                                                  const char       *checksum,
-                                                 GInputStream     *content,
-                                                 guint64           content_length,
+                                                 GInputStream     *object_input,
+                                                 guint64           length,
                                                  GCancellable     *cancellable,
                                                  GError          **error);
 
 void          ostree_repo_stage_content_async (OstreeRepo              *self,
                                                const char              *expected_checksum,
                                                GInputStream            *object,
-                                               guint64                  file_object_length,
+                                               guint64                  length,
                                                GCancellable            *cancellable,
                                                GAsyncReadyCallback      callback,
                                                gpointer                 user_data);
@@ -184,7 +192,7 @@ gboolean      ostree_repo_load_variant (OstreeRepo  *self,
                                         GError       **error);
 
 gboolean      ostree_repo_load_variant_if_exists (OstreeRepo  *self,
-                                                  OstreeObjectType expected_type,
+                                                  OstreeObjectType objtype,
                                                   const char    *sha256, 
                                                   GVariant     **out_variant,
                                                   GError       **error);