[libpeas] Update PeasActivatable and PeasUIConfigurable documentation.

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

commit bdc28f200f301e4658e09748880edd7c18e46d57
Author: Steve Frécinaux <code istique net>
Date:   Tue Jul 27 21:13:13 2010 +0200

    Update PeasActivatable and PeasUIConfigurable documentation.

 libpeas/peas-activatable.c       |   33 ++++++++++++++++++++++++++-------
 libpeasui/peas-ui-configurable.c |   22 ++++++++++++++--------
 2 files changed, 40 insertions(+), 15 deletions(-)
---
diff --git a/libpeas/peas-activatable.c b/libpeas/peas-activatable.c
index c922b30..f8d73dd 100644
--- a/libpeas/peas-activatable.c
+++ b/libpeas/peas-activatable.c
@@ -32,12 +32,17 @@
  *
  * #PeasActivatable is an interface which should be implemented by extensions
  * that should be activated on an object of a certain type (depending on the
- * application). For instance, in gedit, #PeasActivatable extension instances
- * are bound to individual windows.
+ * application). For instance, in a typical windowed application,
+ * #PeasActivatable extension instances could be bound to individual toplevel
+ * windows.
  *
  * It is typical to use #PeasActivatable along with #PeasExtensionSet in order
  * to activate and deactivate extensions automatically when plugins are loaded
- * or unloaded. 
+ * or unloaded.
+ *
+ * You can also use the code of this interface as a base for your own
+ * extension types, as illustrated by gedit's #GeditWindowActivatable and
+ * #GeditDocumentActivatable interfaces.
  **/
 
 G_DEFINE_INTERFACE(PeasActivatable, peas_activatable, G_TYPE_OBJECT)
@@ -45,6 +50,13 @@ G_DEFINE_INTERFACE(PeasActivatable, peas_activatable, G_TYPE_OBJECT)
 void
 peas_activatable_default_init (PeasActivatableInterface *iface)
 {
+  /**
+   * PeasActivatable:object:
+   *
+   * The object property contains the targetted object for this
+   * #PeasActivatable instance, for example a toplevel window in a typical
+   * windowed application. It is set at construction time and won't change.
+   */
   g_object_interface_install_property (iface,
                                        g_param_spec_object ("object",
                                                             "Object",
@@ -59,7 +71,10 @@ peas_activatable_default_init (PeasActivatableInterface *iface)
  * peas_activatable_activate:
  * @activatable: A #PeasActivatable.
  *
- * Activates the extension on the given object.
+ * Activates the extension on the targetted object.
+ *
+ * On activation, the extension should hook itself to the object
+ * where it makes sense.
  */
 void
 peas_activatable_activate (PeasActivatable *activatable)
@@ -77,7 +92,11 @@ peas_activatable_activate (PeasActivatable *activatable)
  * peas_activatable_deactivate:
  * @activatable: A #PeasActivatable.
  *
- * Deactivates the plugin on the given object.
+ * Deactivates the extension on the targetted object.
+ *
+ * On deactivation, an extension should remove itself from all the hooks it
+ * used and should perform any cleanup required, so it can be unreffed safely
+ * and without any more effect on the host application.
  */
 void
 peas_activatable_deactivate (PeasActivatable *activatable)
@@ -95,8 +114,8 @@ peas_activatable_deactivate (PeasActivatable *activatable)
  * peas_activatable_update_state:
  * @activatable: A #PeasActivatable.
  *
- * Triggers an update of the plugin's internal state to take into account
- * state changes in the targetted object, due to a plugin or user action.
+ * Triggers an update of the extension internal state to take into account
+ * state changes in the targetted object, due to some event or user action.
  */
 void
 peas_activatable_update_state (PeasActivatable *activatable)
diff --git a/libpeasui/peas-ui-configurable.c b/libpeasui/peas-ui-configurable.c
index 85a6215..e3aab08 100644
--- a/libpeasui/peas-ui-configurable.c
+++ b/libpeasui/peas-ui-configurable.c
@@ -27,16 +27,16 @@
 
 /**
  * SECTION:peas-ui-configurable
- * @short_description: Interface for configurable plugins.
+ * @short_description: Interface to provide a plugin configuration UI
  *
- * The #PeasUIConfigurable interface will allow a #PeasPlugin to provide a
+ * The #PeasUIConfigurable interface will allow a plugin to provide a
  * graphical interface for the user to configure the plugin through the
- * #PeasUIPluginManager: the #PeasUIPluginManager will make the â??Configure
+ * #PeasUIPluginManager: the #PeasUIPluginManager will make its â??Configure
  * Pluginâ?? button active when the selected plugin implements the
  * #PeasUIConfigurable interface.
  *
- * To do so, the plugin writer will just need to implement the
- * create_configure_widget() method.
+ * To allow plugin configuration from the #PeasUIPluginManager, the plugin
+ * writer will just need to implement the create_configure_widget() method.
  **/
 
 G_DEFINE_INTERFACE(PeasUIConfigurable, peas_ui_configurable, G_TYPE_OBJECT)
@@ -50,11 +50,17 @@ peas_ui_configurable_default_init (PeasUIConfigurableInterface *iface)
  * peas_ui_configurable_create_configure_widget:
  * @configurable: A #PeasUIConfigurable
  *
- * Creates the configure widget widget for the plugin.
+ * Creates the configure widget widget for the plugin. The returned widget
+ * should allow configuring all the relevant aspects of the plugin, and should
+ * allow instant-apply, as promoted by the Gnome Human Interface Guidelines.
  *
- * The default implementation returns %NULL.
+ * #PeasUIPluginManager will embed the returned widget into a dialog box,
+ * but you shouldn't take this behaviour for granted as other implementations
+ * of a plugin manager UI might do otherwise.
  *
- * Returns: A #GtkWindow used for configuration.
+ * This method should always return a valid #GtkWidget instance, never %NULL.
+ *
+ * Returns: A #GtkWidget used for configuration.
  */
 GtkWidget *
 peas_ui_configurable_create_configure_widget (PeasUIConfigurable  *configurable)