[libpeas] Add some more documentation to PeasExtension.

[Steve Frécinaux <sfre src gnome org>]

commit 4f61ae63ed4b448da9dabc28e4ff6073f2cfeac4
Author: Steve Frécinaux <code istique net>
Date:   Thu Jul 22 12:23:20 2010 +0200

    Add some more documentation to PeasExtension.

 docs/reference/libpeas-sections.txt |    7 +++-
 libpeas/peas-extension-set.c        |    4 +++
 libpeas/peas-extension-set.h        |    6 ++++
 libpeas/peas-extension.c            |   47 ++++++++++++++++++++++++++++++++--
 libpeas/peas-extension.h            |   19 +++++++++----
 5 files changed, 72 insertions(+), 11 deletions(-)
---
diff --git a/docs/reference/libpeas-sections.txt b/docs/reference/libpeas-sections.txt
index a295882..fc35949 100644
--- a/docs/reference/libpeas-sections.txt
+++ b/docs/reference/libpeas-sections.txt
@@ -156,8 +156,7 @@ peas_ui_plugin_info_get_icon_name
 
 <SECTION>
 <FILE>peas-plugin-info</FILE>
-PEAS_TYPE_PLUGIN_INFO
-PEAS_PLUGIN_INFO
+<TITLE>PeasPluginInfo</TITLE>
 PeasPluginInfo
 peas_plugin_info_get_type
 peas_plugin_info_is_loaded
@@ -174,5 +173,9 @@ peas_plugin_info_get_copyright
 peas_plugin_info_get_version
 peas_plugin_info_get_iage
 peas_plugin_info_get_keys
+<SUBSECTION Standard>
+PEAS_TYPE_PLUGIN_INFO
+PEAS_PLUGIN_INFO
+</SUBSECTION>
 </SECTION>
 
diff --git a/libpeas/peas-extension-set.c b/libpeas/peas-extension-set.c
index e15ab5c..c8f2cb3 100644
--- a/libpeas/peas-extension-set.c
+++ b/libpeas/peas-extension-set.c
@@ -308,6 +308,8 @@ peas_extension_set_class_init (PeasExtensionSetClass *klass)
  *
  * Call a method on all the #PeasExtension instances contained in @set.
  *
+ * See peas_extension_call() for more information.
+ *
  * Return value: %TRUE on successful call.
  */
 gboolean
@@ -333,6 +335,8 @@ peas_extension_set_call (PeasExtensionSet *set,
  *
  * Call a method on all the #PeasExtension instances contained in @set.
  *
+ * See peas_extension_call_valist() for more information.
+ *
  * Return value: %TRUE on successful call.
  */
 gboolean
diff --git a/libpeas/peas-extension-set.h b/libpeas/peas-extension-set.h
index 4aa78c0..7925c27 100644
--- a/libpeas/peas-extension-set.h
+++ b/libpeas/peas-extension-set.h
@@ -41,6 +41,12 @@ typedef struct _PeasExtensionSet         PeasExtensionSet;
 typedef struct _PeasExtensionSetClass    PeasExtensionSetClass;
 typedef struct _PeasExtensionSetPrivate  PeasExtensionSetPrivate;
 
+/**
+ * PeasExtensionSet:
+ *
+ * The #PeasExtensionSet structure contains only private data and should only
+ * be accessed using the provided API.
+ */
 struct _PeasExtensionSet {
   GObject parent;
 
diff --git a/libpeas/peas-extension.c b/libpeas/peas-extension.c
index 9734c2b..3677596 100644
--- a/libpeas/peas-extension.c
+++ b/libpeas/peas-extension.c
@@ -30,9 +30,34 @@
  * @short_description: Proxy for extensions.
  * @see_also: #PeasExtensionSet
  *
- * A #PeasExtension is an object which proxies an actual extension.  The
- * application writer will use these objects in order to call methods on
- * an instance of an actual extension exported by a loaded plugin.
+ * #PeasExtension is a proxy class used to access actual extensions
+ * implemented using various languages.  As such, the application writer will
+ * use #PeasExtension instances to call methods on extension provided by
+ * loaded plugins.
+ *
+ * To properly use the proxy instances, you will need GObject-introspection
+ * data for the #GInterface or #GObjectClass you want to use as extension
+ * point.  For instance, if you wish to use #PeasActivatable, you will need to
+ * put the following code excerpt in the engine initialization code, in order
+ * to load the required "Peas" typelib:
+ *
+ * |[
+ * g_irepository_require (g_irepository_get_default (),
+ *                        "Peas", "1.0", 0, NULL);
+ * ]|
+ *
+ * You should proceed the same way for any namespace which provides interfaces
+ * you want to use as extension points. GObject-introspection data is required
+ * for all the supported languages, even for C.
+ *
+ * #PeasExtension does not provide any way to access the underlying object.
+ * The main reason is that some loaders may not rely on proper GObject
+ * inheritance for the definition of extensions, and hence it would not be
+ * possible for libpeas to provide a functional GObject instance at all.
+ * Another reason is that it makes reference counting issues easier to deal
+ * with.
+ *
+ * See peas_extension_call() for more information.
  **/
 
 G_DEFINE_ABSTRACT_TYPE (PeasExtension, peas_extension, G_TYPE_OBJECT);
@@ -55,6 +80,20 @@ peas_extension_class_init (PeasExtensionClass *klass)
  *
  * Call a method of the object behind @extension.
  *
+ * The arguments provided to this functions should be of the same type as
+ * those defined in the #GInterface or #GObjectClass used as a base for the
+ * proxied extension. They should be provided in the same order, and if its
+ * return type is not void, then a pointer to a variable of that type should
+ * be passed as the last argument.
+ *
+ * For instance, if the method protoype is:
+ * |[ gint (*my_method) (MyClass *instance, const gchar *str, SomeObject *obj); ]|
+ * you should call peas_extension_call() this way:
+ * |[ peas_extension_call (extension, "my_method", "some_str", obj, &gint_var); ]|
+ *
+ * This function will not do anything if the introspection data for the proxied
+ * object's class has not been loaded previously through g_irepository_require().
+ *
  * Return value: %TRUE on successful call.
  */
 gboolean
@@ -80,6 +119,8 @@ peas_extension_call (PeasExtension *exten,
  *
  * Call a method of the object behind @extension, using @args as arguments.
  *
+ * See peas_extension_call() for more information.
+ *
  * Return value: %TRUE on successful call.
  */
 gboolean
diff --git a/libpeas/peas-extension.h b/libpeas/peas-extension.h
index cec650d..e5ee981 100644
--- a/libpeas/peas-extension.h
+++ b/libpeas/peas-extension.h
@@ -36,23 +36,30 @@ G_BEGIN_DECLS
 #define PEAS_IS_EXTENSION_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), PEAS_TYPE_EXTENSION))
 #define PEAS_EXTENSION_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj), PEAS_TYPE_EXTENSION, PeasExtensionClass))
 
+typedef struct _PeasExtension       PeasExtension;
+typedef struct _PeasExtensionClass  PeasExtensionClass;
+
 /**
  * PeasExtension:
- * @parent: the parent object.
  *
- * Base class for plugins.
+ * The #PeasExtension structure contains only private data and should only be
+ * accessed using the provided API.
  */
-typedef struct _PeasExtension       PeasExtension;
-typedef struct _PeasExtensionClass  PeasExtensionClass;
-
 struct _PeasExtension {
   GObject parent;
 };
 
+/**
+ * PeasExtensionClass:
+ *
+ * The #PeasExtensionClass structure contains only private data and should
+ * only be accessed using the provided API.  You should not inherit from this
+ * class.
+ */
 struct _PeasExtensionClass {
   GObjectClass parent_class;
 
-  /* Virtual public methods */
+  /*< private >*/
   gboolean   (*call)                      (PeasExtension  *exten,
                                            const gchar    *method,
                                            va_list         args);