[libcloudproviders: 5/9] general: Document basic funcionality

[Gitlab System User <gitlab src gnome org>]

commit beb90619836a9136b8595734f21407ced9affa22
Author: Carlos Soriano <csoriano gnome org>
Date:   Thu Aug 31 21:21:57 2017 +0200

    general: Document basic funcionality

 docs/reference/libcloudproviders-docs.xml | 17 +++++--
 src/cloudprovider.c                       | 81 +++++++++++++++++++++++++++++++
 src/cloudproviderproxy.c                  | 12 +++++
 src/cloudproviders.c                      | 18 ++++++-
 4 files changed, 122 insertions(+), 6 deletions(-)
---
diff --git a/docs/reference/libcloudproviders-docs.xml b/docs/reference/libcloudproviders-docs.xml
index 75aba09..b82a95e 100644
--- a/docs/reference/libcloudproviders-docs.xml
+++ b/docs/reference/libcloudproviders-docs.xml
@@ -6,9 +6,7 @@
 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude";>
   <bookinfo>
     <title>CloudProviders Reference Manual</title>
-    <releaseinfo>
-      for cloudproviders &version;
-    </releaseinfo>
+    <releaseinfo>Cloudproviders &version;</releaseinfo>
     <authorgroup>
       <author>
         <firstname>Julius</firstname>
@@ -19,10 +17,21 @@
           </address>
         </affiliation>
       </author>
+      <author>
+        <firstname>Carlos</firstname>
+        <surname>Soriano</surname>
+        <affiliation>
+          <address>
+            <email>csoriano gnome org</email>
+          </address>
+        </affiliation>
+      </author>
     </authorgroup>
     <copyright>
       <year>2017</year>
       <holder>Julius Härtl</holder>
+      <year>2017</year>
+      <holder>Carlos Soriano</holder>
     </copyright>
   </bookinfo>
 
@@ -35,7 +44,7 @@
     </partintro>
     <xi:include href="xml/cloudprovider.xml"/>
     <xi:include href="xml/cloudproviders.xml"/>
-    <xi:include href="xml/cloudprovidermanager.xml"/>
+    <xi:include href="xml/cloudproviderproxy.xml"/>
   </reference>
 
   <reference id="cloudproviders-dbus">
diff --git a/src/cloudprovider.c b/src/cloudprovider.c
index 8eb6e67..3ed9f3b 100644
--- a/src/cloudprovider.c
+++ b/src/cloudprovider.c
@@ -35,6 +35,29 @@ typedef struct
 
 G_DEFINE_TYPE_WITH_PRIVATE (CloudProvider, cloud_provider, G_TYPE_OBJECT)
 
+/**
+ * SECTION:cloudprovider
+ * @title: CloudProvider
+ * @short_description: Base object for representing a single provider
+ * @include: src/cloudprovider.h
+ *
+ * #CloudProvider is the basic object that interacts with UI and actions that a
+ * provider will present to the user.
+ * list view. Extensions can provide #NautilusColumn by registering a
+ * #NautilusColumnProvider and returning them from
+ * nautilus_column_provider_get_columns(), which will be called by the main
+ * application when creating a view.
+ */
+
+/**
+ * cloud_provider_export_account:
+ * @self: The cloud provider
+ * @account_name: The name of the account
+ * @account: The account object
+ *
+ * Each cloud provider can have a variety of account associated with it. Use this
+ * function to export the accounts the user set up.
+ */
 void
 cloud_provider_add_account (CloudProvider* cloud_provider, CloudProviderAccount *account)
 {
@@ -62,6 +85,14 @@ cloud_provider_export_account(CloudProvider* self,
   g_free(object_path);
 }
 
+/**
+ * cloud_provider_unexport_account:
+ * @self: The cloud provider
+ * @account_name: The name of the account
+ *
+ * Each cloud provider can have a variety of account associated with it. Use this
+ * function to remove an already set up account.
+ */
 void
 cloud_provider_unexport_account(CloudProvider *self,
                                 const gchar   *account_name)
@@ -83,6 +114,15 @@ cloud_provider_unexport_account(CloudProvider *self,
   g_free (object_path);
 }
 
+/**
+ * cloud_provider_export_menu:
+ * @self: The cloud provider
+ * @account_name: The name of the account
+ *
+ * One of the benefits of the integration is to display a menu with available
+ * options for an account. Use this function to export a GMenuModel menu to be
+ * displayed by the choosen integration by the desktop environment or application.
+ */
 guint
 cloud_provider_export_menu(CloudProvider *self,
                            const gchar   *account_name,
@@ -102,6 +142,13 @@ cloud_provider_export_menu(CloudProvider *self,
   return *export_id;
 }
 
+/**
+ * cloud_provider_unexport_menu:
+ * @self: The cloud provider
+ * @account_name: The name of the account
+ *
+ * Remove the menu added with cloud_provider_export_menu
+ */
 void
 cloud_provider_unexport_menu(CloudProvider *self,
                              const gchar   *account_name)
@@ -116,6 +163,16 @@ cloud_provider_unexport_menu(CloudProvider *self,
   }
 }
 
+/**
+ * cloud_provider_action_group:
+ * @self: The cloud provider
+ * @account_name: The name of the account
+ * @action_group: The GActionGroup to be used by the menu exported by cloud_provider_export_menu
+ *
+ * In order for a menu exported with cloud_provider_export_menu to receive events
+ * that will eventually call your callbacks, it needs the corresponding GAcionGroup.
+ * Use this function to export it.
+ */
 guint
 cloud_provider_export_action_group(CloudProvider *self,
                                    const gchar   *account_name,
@@ -135,6 +192,13 @@ cloud_provider_export_action_group(CloudProvider *self,
   return *export_id;
 }
 
+/**
+ * cloud_provider_unexport_action_group:
+ * @self: The cloud provider
+ * @account_name: The name of the account
+ *
+ * Unexport the GActionGroup exported by cloud_provider_export_action_group
+ */
 void
 cloud_provider_unexport_action_group(CloudProvider *self,
                                      const gchar   *account_name)
@@ -149,6 +213,15 @@ cloud_provider_unexport_action_group(CloudProvider *self,
   }
 }
 
+/**
+ * cloud_provider_export_objects:
+ * @self: The cloud provider
+ *
+ * Export all objects assigned previously with functions like cloud_provider_export_menu
+ * to DBUS.
+ * Use this function after exporting all the required object to avoid multiple signals
+ * being emitted in a short time.
+ */
 void
 cloud_provider_export_objects(CloudProvider* self)
 {
@@ -156,6 +229,14 @@ cloud_provider_export_objects(CloudProvider* self)
   g_dbus_object_manager_server_set_connection (priv->manager, priv->bus);
 }
 
+/**
+ * cloud_provider_emit_changed:
+ * @self: The cloud provider
+ * @account_name: The name of the account
+ *
+ * When an account changes its status, emit a signal to DBUS using this function
+ * so clients are aware of the change.
+ */
 void
 cloud_provider_emit_changed (CloudProvider *self,
                              const gchar   *account_name)
diff --git a/src/cloudproviderproxy.c b/src/cloudproviderproxy.c
index 4179845..0db952d 100644
--- a/src/cloudproviderproxy.c
+++ b/src/cloudproviderproxy.c
@@ -41,6 +41,18 @@ typedef struct
 
 G_DEFINE_TYPE_WITH_PRIVATE (CloudProviderProxy, cloud_provider_proxy, G_TYPE_OBJECT)
 
+/**
+ * SECTION:cloudproviderproxy
+ * @title: CloudProviderProxy
+ * @short_description: Base object for representing a single provider for clients.
+ * @include: src/cloudproviderproxy.h
+ *
+ * #CloudProviderProxy is the basic object used to construct the integrator UI
+ * and actions that a provider will present to the user, from the client side.
+ * Integrators of the cloud providers can use this object to poll the
+ * #CloudProvider menus, status and actions.
+ */
+
 enum {
   CHANGED,
   READY,
diff --git a/src/cloudproviders.c b/src/cloudproviders.c
index 36e0995..28195b0 100644
--- a/src/cloudproviders.c
+++ b/src/cloudproviders.c
@@ -41,6 +41,18 @@ typedef struct
 
 G_DEFINE_TYPE_WITH_PRIVATE (CloudProviders, cloud_providers, G_TYPE_OBJECT)
 
+/**
+ * SECTION:cloudproviders
+ * @title: CloudProviders
+ * @short_description: Singleton for tracking all providers.
+ * @include: src/cloudproviders.h
+ *
+ * #CloudProviders is a singleton to track all the changes in all providers.
+ * Using a #CloudProviders you can implement integration for all of them at once
+ * and represent them in the UI, track new providers added or removed and their
+ * status.
+ */
+
 enum
 {
   CHANGED,
@@ -134,8 +146,10 @@ on_bus_acquired (GObject      *source_object,
 }
 
 /**
- * cloud_providers_dup_singleton
- * Returns: (transfer none): A manager singleton
+ * cloud_providers_dup_singleton:
+ * Main object to track changes in all providers.
+ *
+ * Returns: (transfer full): A manager singleton
  */
 CloudProviders *
 cloud_providers_dup_singleton (void)