[ostree] doc: Add some more OstreeSysroot docs

[Colin Walters <walters src gnome org>]

commit b88c4b5c1c93ff3b5bf30cd1cf61827be794536d
Author: Colin Walters <walters verbum org>
Date:   Sun Sep 15 22:44:25 2013 -0400

    doc: Add some more OstreeSysroot docs

 doc/ostree-docs.xml                   |    1 +
 doc/ostree-sections.txt               |   21 +++++++++++
 src/libostree/ostree-sysroot-deploy.c |   64 +++++++++++++++++++++++++--------
 src/libostree/ostree-sysroot.h        |    4 +-
 4 files changed, 73 insertions(+), 17 deletions(-)
---
diff --git a/doc/ostree-docs.xml b/doc/ostree-docs.xml
index 0b50ea3..642198a 100644
--- a/doc/ostree-docs.xml
+++ b/doc/ostree-docs.xml
@@ -22,6 +22,7 @@
                <xi:include href="xml/libostree-core.xml"/>
                <xi:include href="xml/libostree-repo.xml"/>
                <xi:include href="xml/libostree-mutable-tree.xml"/>
+               <xi:include href="xml/libostree-sysroot.xml"/>
 
                <index id="api-index-full">
                        <title>API Index</title>
diff --git a/doc/ostree-sections.txt b/doc/ostree-sections.txt
index e4233db..9bcedce 100644
--- a/doc/ostree-sections.txt
+++ b/doc/ostree-sections.txt
@@ -132,3 +132,24 @@ ostree_mutable_tree_walk
 ostree_mutable_tree_get_subdirs
 ostree_mutable_tree_get_files
 </SECTION>
+
+<SECTION>
+<FILE>libostree-sysroot</FILE>
+OstreeSysroot
+ostree_sysroot_get_type
+ostree_sysroot_new
+ostree_sysroot_new_default
+ostree_sysroot_get_path
+ostree_sysroot_ensure_initialized
+ostree_sysroot_read_current_subbootversion
+ostree_sysroot_list_deployments
+ostree_sysroot_get_deployment_directory
+ostree_sysroot_get_deployment_origin_path
+ostree_sysroot_cleanup
+ostree_sysroot_get_repo
+ostree_sysroot_find_booted_deployment
+ostree_sysroot_require_deployment_or_osname
+ostree_sysroot_write_deployments
+ostree_sysroot_deploy
+ostree_sysroot_get_merge_deployment
+</SECTION>
diff --git a/src/libostree/ostree-sysroot-deploy.c b/src/libostree/ostree-sysroot-deploy.c
index 38e182c..c295beb 100644
--- a/src/libostree/ostree-sysroot-deploy.c
+++ b/src/libostree/ostree-sysroot-deploy.c
@@ -982,8 +982,22 @@ swap_bootloader (OstreeSysroot  *sysroot,
   return ret;
 }
 
+/**
+ * ostree_sysroot_write_deployments:
+ * @self: Sysroot
+ * @current_bootversion: 0 or 1 for active boot version
+ * @new_bootversion: 0 or 1 for new bootversion
+ * @new_deployments: (element-type OstreeDeployment): List of new deployments
+ * @cancellable: Cancellable
+ * @error: Error
+ *
+ * Complete the deployment of @new_deployments by updating either the
+ * bootloader configuration (if @current_bootversion and the new
+ * version @new_bootversion differ), or swapping the bootlinks if
+ * they're the same.
+ */
 gboolean
-ostree_sysroot_write_deployments (OstreeSysroot     *sysroot,
+ostree_sysroot_write_deployments (OstreeSysroot     *self,
                                   int                current_bootversion,
                                   int                new_bootversion,
                                   GPtrArray         *new_deployments,
@@ -992,7 +1006,7 @@ ostree_sysroot_write_deployments (OstreeSysroot     *sysroot,
 {
   gboolean ret = FALSE;
   guint i;
-  gs_unref_object OstreeBootloader *bootloader = _ostree_sysroot_query_bootloader (sysroot);
+  gs_unref_object OstreeBootloader *bootloader = _ostree_sysroot_query_bootloader (self);
 
   if (bootloader)
     g_print ("Detected bootloader: %s\n", _ostree_bootloader_get_name (bootloader));
@@ -1007,7 +1021,7 @@ ostree_sysroot_write_deployments (OstreeSysroot     *sysroot,
           goto out;
         }
 
-      if (!swap_bootlinks (sysroot, current_bootversion,
+      if (!swap_bootlinks (self, current_bootversion,
                            new_deployments,
                            cancellable, error))
         {
@@ -1020,7 +1034,7 @@ ostree_sysroot_write_deployments (OstreeSysroot     *sysroot,
       for (i = 0; i < new_deployments->len; i++)
         {
           OstreeDeployment *deployment = new_deployments->pdata[i];
-          if (!install_deployment_kernel (sysroot, new_bootversion,
+          if (!install_deployment_kernel (self, new_bootversion,
                                           deployment, new_deployments->len,
                                           cancellable, error))
             {
@@ -1030,7 +1044,7 @@ ostree_sysroot_write_deployments (OstreeSysroot     *sysroot,
         }
 
       /* Swap bootlinks for *new* version */
-      if (!swap_bootlinks (sysroot, new_bootversion, new_deployments,
+      if (!swap_bootlinks (self, new_bootversion, new_deployments,
                            cancellable, error))
         {
           g_prefix_error (error, "Generating new bootlinks: ");
@@ -1050,7 +1064,7 @@ ostree_sysroot_write_deployments (OstreeSysroot     *sysroot,
             goto out;
           }
 
-      if (!swap_bootloader (sysroot, current_bootversion, new_bootversion,
+      if (!swap_bootloader (self, current_bootversion, new_bootversion,
                             cancellable, error))
         {
           g_prefix_error (error, "Final bootloader swap: ");
@@ -1063,8 +1077,28 @@ ostree_sysroot_write_deployments (OstreeSysroot     *sysroot,
   return ret;
 }
                             
+/**
+ * ostree_sysroot_deploy:
+ * @current_bootversion: Active bootversion
+ * @current_deployments: (element-type OstreeDeployment): Active deployments
+ * @osname: (allow-none): osname to use for merge deployment
+ * @revision: Checksum to add
+ * @origin: (allow-none): Origin to use for upgrades
+ * @add_kernel_argv: (allow-none): Append these arguments to kernel configuration
+ * @retain: If %TRUE, then do not delete earlier deployment
+ * @booted_deployment: (allow-none): Retain this deployment
+ * @provided_merge_deployment: (allow-none): Use this deployment for merge path
+ * @out_new_deployment: (out): The new deployment path
+ * @out_new_bootversion: (out): The new bootversion
+ * @out_new_deployments: (out) (element-type OstreeDeployment): Full list of new deployments
+ * @cancellable: Cancellable
+ * @error: Error
+ *
+ * Add a new deployment with revision @revision; if @retain is %FALSE,
+ * then an earlier deployment will be garbage collected.
+ */
 gboolean
-ostree_sysroot_deploy (OstreeSysroot     *sysroot,
+ostree_sysroot_deploy (OstreeSysroot     *self,
                        int                current_bootversion,
                        GPtrArray         *current_deployments,
                        const char        *osname,
@@ -1093,7 +1127,7 @@ ostree_sysroot_deploy (OstreeSysroot     *sysroot,
   gs_unref_ptrarray GPtrArray *new_deployments = NULL;
   int new_bootversion;
 
-  if (!ostree_sysroot_get_repo (sysroot, &repo, cancellable, error))
+  if (!ostree_sysroot_get_repo (self, &repo, cancellable, error))
     goto out;
 
   /* Here we perform cleanup of any leftover data from previous
@@ -1103,7 +1137,7 @@ ostree_sysroot_deploy (OstreeSysroot     *sysroot,
    * TODO: Add /ostree/transaction file, and only do this cleanup if
    * we find it.
    */
-  if (!ostree_sysroot_cleanup (sysroot, cancellable, error))
+  if (!ostree_sysroot_cleanup (self, cancellable, error))
     {
       g_prefix_error (error, "Performing initial cleanup: ");
       goto out;
@@ -1150,14 +1184,14 @@ ostree_sysroot_deploy (OstreeSysroot     *sysroot,
   print_deployment_diff (current_deployments, new_deployments);
 
   /* Check out the userspace tree onto the filesystem */
-  if (!checkout_deployment_tree (sysroot, repo, new_deployment, &new_deployment_path,
+  if (!checkout_deployment_tree (self, repo, new_deployment, &new_deployment_path,
                                  cancellable, error))
     {
       g_prefix_error (error, "Checking out tree: ");
       goto out;
     }
 
-  if (!write_origin_file (sysroot, new_deployment, cancellable, error))
+  if (!write_origin_file (self, new_deployment, cancellable, error))
     {
       g_prefix_error (error, "Writing out origin file: ");
       goto out;
@@ -1169,7 +1203,7 @@ ostree_sysroot_deploy (OstreeSysroot     *sysroot,
   bootconfig = ostree_bootconfig_parser_new ();
   ostree_deployment_set_bootconfig (new_deployment, bootconfig);
 
-  if (!merge_configuration (sysroot, merge_deployment, new_deployment,
+  if (!merge_configuration (self, merge_deployment, new_deployment,
                             new_deployment_path,
                             cancellable, error))
     {
@@ -1204,7 +1238,7 @@ ostree_sysroot_deploy (OstreeSysroot     *sysroot,
       ostree_bootconfig_parser_set (bootconfig, "options", new_options);
     }
 
-  if (!ostree_sysroot_write_deployments (sysroot, current_bootversion, new_bootversion,
+  if (!ostree_sysroot_write_deployments (self, current_bootversion, new_bootversion,
                                          new_deployments, cancellable, error))
     goto out;
 
@@ -1216,7 +1250,7 @@ ostree_sysroot_deploy (OstreeSysroot     *sysroot,
    * done from the host.
    */
   {
-    gs_unref_object GFile *osdir = ot_gfile_resolve_path_printf (sysroot->path, "ostree/deploy/%s", 
ostree_deployment_get_osname (new_deployment));
+    gs_unref_object GFile *osdir = ot_gfile_resolve_path_printf (self->path, "ostree/deploy/%s", 
ostree_deployment_get_osname (new_deployment));
     gs_unref_object GFile *os_current_path = g_file_get_child (osdir, "current");
     gs_free char *target = g_file_get_relative_path (osdir, new_deployment_path);
     g_assert (target != NULL);
@@ -1227,7 +1261,7 @@ ostree_sysroot_deploy (OstreeSysroot     *sysroot,
 
   /* And finally, cleanup of any leftover data.
    */
-  if (!ostree_sysroot_cleanup (sysroot, cancellable, error))
+  if (!ostree_sysroot_cleanup (self, cancellable, error))
     {
       g_prefix_error (error, "Performing final cleanup: ");
       goto out;
diff --git a/src/libostree/ostree-sysroot.h b/src/libostree/ostree-sysroot.h
index 09db378..9ae1fe8 100644
--- a/src/libostree/ostree-sysroot.h
+++ b/src/libostree/ostree-sysroot.h
@@ -84,14 +84,14 @@ gboolean ostree_sysroot_require_deployment_or_osname (OstreeSysroot       *sysro
                                                       GCancellable        *cancellable,
                                                       GError             **error);
 
-gboolean ostree_sysroot_write_deployments (OstreeSysroot     *sysroot,
+gboolean ostree_sysroot_write_deployments (OstreeSysroot     *self,
                                            int                current_bootversion,
                                            int                new_bootversion,
                                            GPtrArray         *new_deployments,
                                            GCancellable      *cancellable,
                                            GError           **error);
 
-gboolean ostree_sysroot_deploy (OstreeSysroot     *sysroot,
+gboolean ostree_sysroot_deploy (OstreeSysroot     *self,
                                 int                current_bootversion,
                                 GPtrArray         *current_deployments,
                                 const char        *osname,