Add some more docs

Signed-off-by: David Zeuthen <davidz@redhat.com>

3 files changed, 54 insertions, 2 deletions

diff --git a/src/goa/goabackendoauth2provider.c b/src/goa/goabackendoauth2provider.c
index abe1531..c77ba1b 100644
--- a/src/goa/goabackendoauth2provider.c
+++ b/src/goa/goabackendoauth2provider.c
@@ -36,7 +36,29 @@
  * @title: GoaBackendOAuth2Provider
  * @short_description: Abstract base class for OAuth 2.0 providers
  *
- * #GoaBackendOAuth2Provider is a base class for all OAuth 2.0 based providers.
+ * #GoaBackendOAuth2Provider is an abstract base class for <ulink
+ * url="http://tools.ietf.org/html/draft-ietf-oauth-v2-15">OAuth
+ * 2.0</ulink> based providers.
+ *
+ * Subclasses must implement
+ * #GoaBackendOAuth2ProviderClass.get_authorization_uri,
+ * #GoaBackendOAuth2ProviderClass.get_token_uri,
+ * #GoaBackendOAuth2ProviderClass.get_redirect_uri,
+ * #GoaBackendOAuth2ProviderClass.get_scope,
+ * #GoaBackendOAuth2ProviderClass.get_client_id,
+ * #GoaBackendOAuth2ProviderClass.get_client_secret,
+ * #GoaBackendOAuth2ProviderClass.get_identity and
+ * #GoaBackendOAuth2ProviderClass.get_identity_finish methods.
+ *
+ * Additionally, the
+ * #GoaBackendProviderClass.get_provider_type,
+ * #GoaBackendProviderClass.get_name,
+ * #GoaBackendProviderClass.build_object (this should chain up to its
+ * parent class) methods must be implemented.
+ *
+ * Note that the #GoaBackendProviderClass.add_account and
+ * #GoaBackendProviderClass.refresh_account methods do not need to be
+ * implemented - this type implements these methods.
  */
 
 G_DEFINE_ABSTRACT_TYPE (GoaBackendOAuth2Provider, goa_backend_oauth2_provider, GOA_TYPE_BACKEND_PROVIDER);
@@ -256,6 +278,9 @@ goa_backend_oauth2_provider_get_client_secret (GoaBackendOAuth2Provider *provide
  * loop</link> this method was called from. You can then call
  * goa_backend_oauth2_provider_get_identity_finish() to get the result
  * of the operation.
+ *
+ * This is a pure virtual method - a subclass must provide an
+ * implementation.
  */
 void
 goa_backend_oauth2_provider_get_identity (GoaBackendOAuth2Provider *provider,
@@ -278,6 +303,9 @@ goa_backend_oauth2_provider_get_identity (GoaBackendOAuth2Provider *provider,
  *
  * Finishes an operation started with goa_backend_oauth2_provider_get_identity().
  *
+ * This is a pure virtual method - a subclass must provide an
+ * implementation.
+ *
  * Returns: The identity or %NULL if error is set. The returned string
  * must be freed with g_free().
  */
diff --git a/src/goa/goabackendprovider.c b/src/goa/goabackendprovider.c
index d0587ff..9f46595 100644
--- a/src/goa/goabackendprovider.c
+++ b/src/goa/goabackendprovider.c
@@ -33,7 +33,7 @@
  * @title: GoaBackendProvider
  * @short_description: Abstract base class for providers
  *
- * #GoaBackendProvider is the base type that all providers implement.
+ * #GoaBackendProvider is the base type for all providers.
  */
 
 G_DEFINE_ABSTRACT_TYPE (GoaBackendProvider, goa_backend_provider, G_TYPE_OBJECT);
@@ -54,6 +54,9 @@ goa_backend_provider_class_init (GoaBackendProviderClass *klass)
  *
  * Gets the type of @provider.
  *
+ * This is a pure virtual method - a subclass must provide an
+ * implementation.
+ *
  * Returns: (transfer none): A string owned by @provider, do not free.
  */
 const gchar *
@@ -70,6 +73,9 @@ goa_backend_provider_get_provider_type (GoaBackendProvider *provider)
  * Gets a localized name for @provider that is suitable for display in
  * an user interface.
  *
+ * This is a pure virtual method - a subclass must provide an
+ * implementation.
+ *
  * Returns: (transfer none): A string owned by @provider, do not free.
  */
 const gchar *
@@ -112,6 +118,9 @@ goa_backend_provider_get_name (GoaBackendProvider *provider)
  * interacting with the user and may do so using e.g. gtk_dialog_run()
  * on @dialog.
  *
+ * This is a pure virtual method - a subclass must provide an
+ * implementation.
+ *
  * Returns: The #GoaObject for the created account (must be relased
  *   with g_object_unref()) or %NULL if @error is set.
  */
@@ -157,6 +166,9 @@ goa_backend_provider_add_account (GoaBackendProvider *provider,
  * linkend="g_main_context_default">default main loop</link> while
  * interacting with the user.
  *
+ * This is a pure virtual method - a subclass must provide an
+ * implementation.
+ *
  * Returns: %TRUE if the account has been refreshed, %FALSE if @error
  * is set.
  */
@@ -197,6 +209,9 @@ goa_backend_provider_refresh_account (GoaBackendProvider  *provider,
  * Note that this may be called on already exported objects - for
  * example on configuration files reload.
  *
+ * This is a pure virtual method - a subclass must provide an
+ * implementation.
+ *
  * Returns: %TRUE if data was valid, %FALSE if @error is set.
  */
 gboolean
@@ -350,6 +365,8 @@ store_password_cb (GnomeKeyringResult result,
  * loop</link> this function was called from. You can then call
  * goa_backend_provider_store_credentials_finish() to get the result
  * of the operation.
+ *
+ * This is a convenience method (not virtual) that subclasses can use.
  */
 void
 goa_backend_provider_store_credentials (GoaBackendProvider   *provider,
@@ -425,6 +442,8 @@ goa_backend_provider_store_credentials (GoaBackendProvider   *provider,
  *
  * Finishes an operation started with goa_backend_provider_store_credentials().
  *
+ * This is a convenience method (not virtual) that subclasses can use.
+ *
  * Returns: %TRUE if the credentials was successfully stored, %FALSE
  * if @error is set.
  */
@@ -520,6 +539,8 @@ find_password_cb (GnomeKeyringResult  result,
  * loop</link> this function was called from. You can then call
  * goa_backend_provider_lookup_credentials_finish() to get the result
  * of the operation.
+ *
+ * This is a convenience method (not virtual) that subclasses can use.
  */
 void
 goa_backend_provider_lookup_credentials (GoaBackendProvider   *provider,
@@ -561,6 +582,8 @@ goa_backend_provider_lookup_credentials (GoaBackendProvider   *provider,
  *
  * Finishes an operation started with goa_backend_provider_lookup_credentials().
  *
+ * This is a convenience method (not virtual) that subclasses can use.
+ *
  * Returns: (element-type utf8 utf8) (transfer full): A #GHashTable
  * with credentials or %NULL if @error is set. Free with
  * g_hash_table_unref().
diff --git a/src/goa/goabackendprovider.h b/src/goa/goabackendprovider.h
index 08c3d8d..0e3f624 100644
--- a/src/goa/goabackendprovider.h
+++ b/src/goa/goabackendprovider.h
@@ -69,6 +69,7 @@ struct _GoaBackendProviderClass
 {
   GObjectClass parent_class;
 
+  /* pure virtual */
   const gchar *(*get_provider_type) (GoaBackendProvider *provider);
   const gchar *(*get_name)          (GoaBackendProvider *provider);
   GoaObject   *(*add_account)       (GoaBackendProvider *provider,