[gnome-online-accounts] Fix and clean up docs

[Debarshi Ray <debarshir src gnome org>]

commit bb6c33b2c740815e64a47d814f458e3643bc9c6f
Author: Debarshi Ray <debarshir gnome org>
Date:   Fri Dec 19 16:22:18 2014 +0100

    Fix and clean up docs
    
    Removed GoaProviderFactory, GoaTelepathyFactory, GoaImapAuthLogin,
    GoaSmtpAuth and utility functions from the public API documentation.
    These are internal APIs that no application developer can or is meant
    to use. Some of the text has been retained as internal documentation
    for gnome-online-accounts hackers.
    
    Fixed the goa_provider_get_all documentation and some cross-referencing
    issues.

 doc/goa-docs.xml                     |    2 --
 doc/goa-sections.txt                 |   32 --------------------------------
 doc/goa.types                        |    7 +++++++
 src/goabackend/goaimapauthlogin.c    |    4 ++--
 src/goabackend/goaprovider.c         |   28 ++--------------------------
 src/goabackend/goaproviderfactory.c  |    8 ++++----
 src/goabackend/goaproviderfactory.h  |    4 ++--
 src/goabackend/goasmtpauth.c         |    4 ++--
 src/goabackend/goatelepathyfactory.c |    2 +-
 9 files changed, 20 insertions(+), 71 deletions(-)
---
diff --git a/doc/goa-docs.xml b/doc/goa-docs.xml
index b33281a..41bd7a8 100644
--- a/doc/goa-docs.xml
+++ b/doc/goa-docs.xml
@@ -166,7 +166,6 @@
       <title>Core</title>
       <xi:include href="xml/goautil.xml"/>
       <xi:include href="xml/goaprovider.xml"/>
-      <xi:include href="xml/goaproviderfactory.xml"/>
       <xi:include href="xml/goaoauthprovider.xml"/>
       <xi:include href="xml/goaoauth2provider.xml"/>
     </chapter>
@@ -180,7 +179,6 @@
       <xi:include href="xml/goayahooprovider.xml"/>
       <xi:include href="xml/goaflickrprovider.xml"/>
       <xi:include href="xml/goafoursquareprovider.xml"/>
-      <xi:include href="xml/goatelepathyfactory.xml"/>
       <xi:include href="xml/goatelepathyprovider.xml"/>
     </chapter>
   </part>
diff --git a/doc/goa-sections.txt b/doc/goa-sections.txt
index d08e1a3..fa196b3 100644
--- a/doc/goa-sections.txt
+++ b/doc/goa-sections.txt
@@ -455,24 +455,6 @@ goa_provider_get_type
 </SECTION>
 
 <SECTION>
-<FILE>goaproviderfactory</FILE>
-GoaProviderFactory
-GoaProviderFactoryClass
-GOA_PROVIDER_FACTORY_EXTENSION_POINT_NAME
-goa_provider_factory_get_provider
-goa_provider_factory_get_providers
-goa_provider_factory_get_providers_finish
-<SUBSECTION Standard>
-GOA_PROVIDER_FACTORY
-GOA_PROVIDER_FACTORY_CLASS
-GOA_PROVIDER_FACTORY_GET_CLASS
-GOA_IS_PROVIDER_FACTORY
-GOA_IS_PROVIDER_FACTORY_CLASS
-GOA_TYPE_PROVIDER_FACTORY
-goa_provider_factory_get_type
-</SECTION>
-
-<SECTION>
 <FILE>goaoauth2provider</FILE>
 GoaOAuth2Provider
 GoaOAuth2ProviderClass
@@ -616,20 +598,6 @@ goa_foursquare_provider_get_type
 </SECTION>
 
 <SECTION>
-<FILE>goatelepathyfactory</FILE>
-GoaTelepathyFactory
-GoaTelepathyFactoryClass
-<SUBSECTION Standard>
-GOA_TELEPATHY_FACTORY
-GOA_TELEPATHY_FACTORY_CLASS
-GOA_TELEPATHY_FACTORY_GET_CLASS
-GOA_IS_TELEPATHY_FACTORY
-GOA_IS_TELEPATHY_FACTORY_CLASS
-GOA_TYPE_TELEPATHY_FACTORY
-goa_telepathy_factory_get_type
-</SECTION>
-
-<SECTION>
 <FILE>goatelepathyprovider</FILE>
 GoaTelepathyProvider
 goa_telepathy_provider_new_from_protocol_name
diff --git a/doc/goa.types b/doc/goa.types
index 9eadc95..e24782e 100644
--- a/doc/goa.types
+++ b/doc/goa.types
@@ -10,7 +10,14 @@ goa_object_get_type
 goa_object_proxy_get_type
 goa_object_skeleton_get_type
 goa_oauth_based_get_type
+goa_oauth_based_proxy_get_type
+goa_oauth_based_skeleton_get_type
 goa_oauth2_based_get_type
+goa_oauth2_based_proxy_get_type
+goa_oauth2_based_skeleton_get_type
+goa_password_based_get_type
+goa_password_based_proxy_get_type
+goa_password_based_skeleton_get_type
 goa_mail_get_type
 goa_mail_proxy_get_type
 goa_mail_skeleton_get_type
diff --git a/src/goabackend/goaimapauthlogin.c b/src/goabackend/goaimapauthlogin.c
index 256b4e7..1678586 100644
--- a/src/goabackend/goaimapauthlogin.c
+++ b/src/goabackend/goaimapauthlogin.c
@@ -27,7 +27,7 @@
 #include "goaprovider.h"
 #include "goautils.h"
 
-/**
+/*
  * SECTION:goaimapauthlogin
  * @title: GoaImapAuthLogin
  * @short_description: LOGIN authentication method for IMAP
@@ -37,7 +37,7 @@
  * authentication method (e.g. using usernames / passwords) for IMAP.
  */
 
-/**
+/*
  * GoaImapAuthLogin:
  *
  * The #GoaImapAuthLogin structure contains only private data
diff --git a/src/goabackend/goaprovider.c b/src/goabackend/goaprovider.c
index e92d8a0..9d99296 100644
--- a/src/goabackend/goaprovider.c
+++ b/src/goabackend/goaprovider.c
@@ -1037,10 +1037,6 @@ out:
  *
  * See goa_provider_get_for_provider_type() for details on how the providers
  * are found.
- *
- * Returns: (transfer full) (element-type GoaProvider): A list
- *   of element providers that should be freed with g_list_free()
- *   after each element has been freed with g_object_unref().
  */
 void
 goa_provider_get_all (GAsyncReadyCallback callback,
@@ -1088,7 +1084,8 @@ goa_provider_get_all (GAsyncReadyCallback callback,
 
 /**
  * goa_provider_get_all_finish:
- * @out_providers: (out): Return location for a list of #GoaProvider instances.
+ * @out_providers: (out) (transfer full) (element-type GoaProvider):
+ * Return location for a list of #GoaProvider instances.
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to goa_provider_get_all().
  * @error: Return location for error or %NULL.
  *
@@ -1159,27 +1156,6 @@ goa_provider_get_preseed_data (GoaProvider *provider)
 
 /* ---------------------------------------------------------------------------------------------------- */
 
-/**
- * SECTION:goautil
- * @title: Utilities
- * @short_description: Various utility routines
- *
- * Various utility routines.
- */
-
-/* ---------------------------------------------------------------------------------------------------- */
-
-/**
- * goa_util_add_row_widget:
- * @left: A #GtkGrid for the left side.
- * @right: A #GtkGrid for the right side.
- * @label_text: (allow-none): The text to insert on the left side or %NULL for no label.
- * @widget: A widget to insert on the right side.
- *
- * Utility function to add @label_text and @widget to @table.
- *
- * Returns: (transfer none): The #GtkWidget that was inserted (e.g. @widget itself).
- */
 GtkWidget *
 goa_util_add_row_widget (GtkGrid      *grid,
                          gint          row,
diff --git a/src/goabackend/goaproviderfactory.c b/src/goabackend/goaproviderfactory.c
index 52e66cc..5c51ceb 100644
--- a/src/goabackend/goaproviderfactory.c
+++ b/src/goabackend/goaproviderfactory.c
@@ -20,7 +20,7 @@
 
 #include "goaproviderfactory.h"
 
-/**
+/*
  * SECTION:goaproviderfactory
  * @title: GoaProviderFactory
  * @short_description: Abstract base class for provider factories
@@ -32,7 +32,7 @@ G_DEFINE_ABSTRACT_TYPE (GoaProviderFactory, goa_provider_factory, G_TYPE_OBJECT)
 
 /* ---------------------------------------------------------------------------------------------------- */
 
-/**
+/*
  * goa_provider_factory_get_provider:
  * @factory: A #GoaProviderFactory.
  * @provider_name: A provider type identifier (ie. IM protocol names in #GoaTelepathyFactory)
@@ -59,7 +59,7 @@ goa_provider_factory_get_provider (GoaProviderFactory  *factory,
 
 /* ---------------------------------------------------------------------------------------------------- */
 
-/**
+/*
  * goa_provider_factory_get_providers:
  * @factory: A #GoaProviderFactory.
  * @callback: The function to call when the request is satisfied.
@@ -90,7 +90,7 @@ goa_provider_factory_get_providers (GoaProviderFactory  *factory,
   return klass->get_providers (factory, callback, user_data);
 }
 
-/**
+/*
  * goa_provider_factory_get_providers_finish:
  * @factory: A #GoaProviderFactory.
  * @out_providers: (out): Return location for a list of #GoaProvider instances handled by @factory.
diff --git a/src/goabackend/goaproviderfactory.h b/src/goabackend/goaproviderfactory.h
index 6eaa23e..a4918af 100644
--- a/src/goabackend/goaproviderfactory.h
+++ b/src/goabackend/goaproviderfactory.h
@@ -39,7 +39,7 @@ G_BEGIN_DECLS
 typedef struct _GoaProviderFactory GoaProviderFactory;
 typedef struct _GoaProviderFactoryClass GoaProviderFactoryClass;
 
-/**
+/*
  * GoaProviderFactory:
  *
  * The #GoaProviderFactory structure contains only private data and should
@@ -51,7 +51,7 @@ struct _GoaProviderFactory
   GObject parent_instance;
 };
 
-/**
+/*
  * GoaProviderFactoryClass:
  * @parent_class: The parent class.
  * @get_provider: Virtual function for goa_provider_factory_get_provider().
diff --git a/src/goabackend/goasmtpauth.c b/src/goabackend/goasmtpauth.c
index 1cc558b..531cc02 100644
--- a/src/goabackend/goasmtpauth.c
+++ b/src/goabackend/goasmtpauth.c
@@ -26,7 +26,7 @@
 #include "goaprovider.h"
 #include "goautils.h"
 
-/**
+/*
  * SECTION:goasmtpauth
  * @title: GoaSmtpAuth
  * @short_description: Authentication mechanisms for SMTP
@@ -37,7 +37,7 @@
  * SASL mechanisms (e.g. using usernames / passwords) for SMTP.
  */
 
-/**
+/*
  * GoaSmtpAuth:
  *
  * The #GoaSmtpAuth structure contains only private data and should
diff --git a/src/goabackend/goatelepathyfactory.c b/src/goabackend/goatelepathyfactory.c
index d59fd53..b0793cb 100644
--- a/src/goabackend/goatelepathyfactory.c
+++ b/src/goabackend/goatelepathyfactory.c
@@ -24,7 +24,7 @@
 #include "goaprovider-priv.h"
 #include "goatelepathyprovider.h"
 
-/**
+/*
  * SECTION:goatelepathyfactory
  * @title: GoaTelepathyFactory
  * @short_description: Factory for #GoaTelepathyProvider instances