GNOME.org
 

[libpeas] Update documentation for most classes of libpeas.

commit 019575ec6a7bc6c5b139845122776a376f58e0d6
Author: Steve Frécinaux <code istique net>
Date:   Sat May 29 15:43:41 2010 +0200

    Update documentation for most classes of libpeas.

 docs/reference/Makefile.am          |    1 -
 docs/reference/libpeas-docs.sgml    |    1 +
 docs/reference/libpeas-sections.txt |   18 ++++++++++++++
 libpeas/peas-activatable.c          |   17 +++++++++----
 libpeas/peas-activatable.h          |    6 ++--
 libpeas/peas-engine.h               |    4 +-
 libpeas/peas-extension-base.c       |   22 +++++++----------
 libpeas/peas-extension-set.c        |   45 +++++++++++++++++++++++++++++++++++
 libpeas/peas-extension.c            |   16 +++++++++++-
 libpeas/peas-extension.h            |    4 +-
 libpeas/peas-object-module.c        |   10 +++++++
 11 files changed, 117 insertions(+), 27 deletions(-)
---
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index f4951f3..ea1ea47 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -51,7 +51,6 @@ IGNORE_HFILES=		\
 	peas-dirs.h			\
 	peas-i18n.h			\
 	peas-marshal.h			\
-	peas-object-module.h		\
 	peas-plugin-loader-c.h		\
 	peas-plugin-loader-python.h	\
 	peas-plugin-loader-seed.h	\
diff --git a/docs/reference/libpeas-docs.sgml b/docs/reference/libpeas-docs.sgml
index bbcda4f..ec43a52 100644
--- a/docs/reference/libpeas-docs.sgml
+++ b/docs/reference/libpeas-docs.sgml
@@ -20,6 +20,7 @@
       <xi:include href="xml/peas-activatable.xml"/>
       <xi:include href="xml/peas-engine.xml"/>
       <xi:include href="xml/peas-extension.xml"/>
+      <xi:include href="xml/peas-object-module.xml"/>
       <xi:include href="xml/peas-extension-base.xml"/>
       <xi:include href="xml/peas-extension-set.xml"/>
       <xi:include href="xml/peas-plugin-info.xml"/>
diff --git a/docs/reference/libpeas-sections.txt b/docs/reference/libpeas-sections.txt
index f349372..38af2d6 100644
--- a/docs/reference/libpeas-sections.txt
+++ b/docs/reference/libpeas-sections.txt
@@ -98,6 +98,24 @@ PeasExtensionSetPrivate
 </SECTION>
 
 <SECTION>
+<FILE>peas-object-module</FILE>
+<TITLE>PeasObjectModule</TITLE>
+PeasObjectModule
+PeasObjectModuleClass
+PeasCreateFunc
+peas_object_module_register_extension
+peas_object_module_register_extension_type
+<SUBSECTION Standard>
+PEAS_OBJECT_MODULE
+PEAS_IS_OBJECT_MODULE
+PEAS_TYPE_OBJECT_MODULE
+peas_object_module_get_type
+PEAS_OBJECT_MODULE_CLASS
+PEAS_IS_OBJECT_MODULE_CLASS
+PEAS_OBJECT_MODULE_GET_CLASS
+</SECTION>
+
+<SECTION>
 <FILE>peas-extension-base</FILE>
 <TITLE>PeasExtensionBase</TITLE>
 PeasExtensionBase
diff --git a/libpeas/peas-activatable.c b/libpeas/peas-activatable.c
index a341b45..e66104a 100644
--- a/libpeas/peas-activatable.c
+++ b/libpeas/peas-activatable.c
@@ -27,7 +27,17 @@
 
 /**
  * SECTION:peas-activatable
- * @short_description: Interface for activatable plugins
+ * @short_description: Interface for activatable extensions
+ * @see_also: #PeasExtensionSet
+ *
+ * #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.
+ *
+ * It is typical to use #PeasActivatable along with #PeasExtensionSet in order
+ * to activate and deactivate extensions automatically when plugins are loaded
+ * or unloaded. 
  **/
 
 G_DEFINE_INTERFACE(PeasActivatable, peas_activatable, G_TYPE_OBJECT)
@@ -42,10 +52,7 @@ peas_activatable_default_init (PeasActivatableInterface *iface)
  * @activatable: A #PeasActivatable.
  * @object: The #GObject on which the plugin should be activated.
  *
- * Activates the plugin on an object.  An instance of #PeasActivatable will be
- * activated once for each object registered against the #PeasEngine which
- * controls this #PeasActivatable.  For instance, a typical GUI application
- * like gedit will activate the plugin once for each of its main windows.
+ * Activates the extension on the given object.
  */
 void
 peas_activatable_activate (PeasActivatable *activatable,
diff --git a/libpeas/peas-activatable.h b/libpeas/peas-activatable.h
index 172569e..58004e3 100644
--- a/libpeas/peas-activatable.h
+++ b/libpeas/peas-activatable.h
@@ -55,11 +55,11 @@ struct _PeasActivatableInterface {
  */
 GType             peas_activatable_get_type       (void)  G_GNUC_CONST;
 
-void              peas_activatable_activate       (PeasActivatable *plugin,
+void              peas_activatable_activate       (PeasActivatable *activatable,
                                                    GObject         *object);
-void              peas_activatable_deactivate     (PeasActivatable *plugin,
+void              peas_activatable_deactivate     (PeasActivatable *activatable,
                                                    GObject         *object);
-void              peas_activatable_update_state   (PeasActivatable *plugin,
+void              peas_activatable_update_state   (PeasActivatable *activatable,
                                                    GObject         *object);
 
 G_END_DECLS
diff --git a/libpeas/peas-engine.h b/libpeas/peas-engine.h
index 500d3a1..e0ebf04 100644
--- a/libpeas/peas-engine.h
+++ b/libpeas/peas-engine.h
@@ -85,10 +85,10 @@ void              peas_engine_garbage_collect     (PeasEngine      *engine);
 
 gboolean          peas_engine_provides_extension  (PeasEngine      *engine,
                                                    PeasPluginInfo  *info,
-                                                   GType            ext_type);
+                                                   GType            extension_type);
 PeasExtension    *peas_engine_get_extension       (PeasEngine      *engine,
                                                    PeasPluginInfo  *info,
-                                                   GType            ext_type);
+                                                   GType            extension_type);
 
 
 G_END_DECLS
diff --git a/libpeas/peas-extension-base.c b/libpeas/peas-extension-base.c
index 3639bec..135645e 100644
--- a/libpeas/peas-extension-base.c
+++ b/libpeas/peas-extension-base.c
@@ -29,22 +29,18 @@
 #include "peas-dirs.h"
 
 /**
- * SECTION:peas-plugin
- * @short_description: Base class for plugins
+ * SECTION:peas-extension-base
+ * @short_description: Base class for C extensions
  * @see_also: #PeasPluginInfo
  *
- * A #PeasExtensionBase is an object which represents an actual loaded plugin.
+ * #PeasExtensionBase can optionally be used as a base class for the extensions
+ * of your plugin. By inheriting from it, you will make your extension able to
+ * access the related #PeasPluginInfo, and especially the location where all
+ * the data of your plugin lives.
  *
- * As a plugin writer, you will need to inherit from this class to perform
- * the actions you want to using the available hooks.  It will also provide
- * you a few useful pieces of information, like the location where all your
- * data lives.
- *
- * As an application developper, you might want to provide a subclass of
- * #PeasExtensionBase for tighter integration with your application.  But you should
- * not use this class at all in your application code apart from that, as all
- * the actions that can be performed by plugins will be proxied by the
- * #PeasEngine.
+ * Non-C extensions will usually not inherit from this class: Python and Seed
+ * ones automatically get a "plugin_info" attribute that serves the same
+ * purpose.
  **/
 
 G_DEFINE_ABSTRACT_TYPE (PeasExtensionBase, peas_extension_base, G_TYPE_OBJECT);
diff --git a/libpeas/peas-extension-set.c b/libpeas/peas-extension-set.c
index 66e258f..3bfcbf5 100644
--- a/libpeas/peas-extension-set.c
+++ b/libpeas/peas-extension-set.c
@@ -29,6 +29,23 @@
 #include "peas-plugin-info.h"
 #include "peas-marshal.h"
 
+/**
+ * SECTION:peas-extension-set
+ * @short_description: Proxy for a set of extensions of the same type.
+ * @see_also: #PeasExtension
+ *
+ * A #PeasExtensionSet is an object which proxies method calls to a set
+ * of actual extensions.  The application writer will use these objects
+ * in order to call methods on several instances of an actual extension
+ * exported by all the currently loaded plugins.
+ *
+ * #PeasExtensionSet will automatically track loading and unloading of
+ * the plugins, and signal appearance and disappearance of new
+ * extension instances.  You should connect to those signals if you
+ * wish to call specific methods on loading or unloading time, as it
+ * is typically the case for #PeasActivatable extensions.
+ **/
+
 G_DEFINE_TYPE (PeasExtensionSet, peas_extension_set, G_TYPE_OBJECT);
 
 struct _PeasExtensionSetPrivate {
@@ -216,6 +233,16 @@ peas_extension_set_class_init (PeasExtensionSetClass *klass)
   g_type_class_add_private (klass, sizeof (PeasExtensionSetPrivate));
 }
 
+/**
+ * peas_extension_set_call:
+ * @set: A #PeasExtensionSet.
+ * @method_name: the name of the method that should be called.
+ * @Varargs: arguments for the method.
+ *
+ * Call a method on all the #PeasExtension instances contained in @set.
+ *
+ * Return value: #TRUE on successful call.
+ */
 gboolean
 peas_extension_set_call (PeasExtensionSet *set,
                          const gchar      *method_name,
@@ -231,6 +258,16 @@ peas_extension_set_call (PeasExtensionSet *set,
   return result;
 }
 
+/**
+ * peas_extension_set_call_valist:
+ * @exten: A #PeasExtensionSet.
+ * @method_name: the name of the method that should be called.
+ * @args: the arguments for the method.
+ *
+ * Call a method on all the #PeasExtension instances contained in @set.
+ *
+ * Return value: #TRUE on successful call.
+ */
 gboolean
 peas_extension_set_call_valist (PeasExtensionSet *set,
                                 const gchar      *method_name,
@@ -245,6 +282,14 @@ peas_extension_set_call_valist (PeasExtensionSet *set,
   return klass->call (set, method_name, args);
 }
 
+/**
+ * peas_extension_set_new:
+ * @engine: A #PeasEngine.
+ * @exten_type: the extension #GType
+ *
+ * Create an #ExtensionSet for all the @exten_type extensions defined in
+ * the plugins loaded in @engine.
+ */
 PeasExtensionSet *
 peas_extension_set_new (PeasEngine *engine,
                         GType       exten_type)
diff --git a/libpeas/peas-extension.c b/libpeas/peas-extension.c
index eadc1ec..efe05c4 100644
--- a/libpeas/peas-extension.c
+++ b/libpeas/peas-extension.c
@@ -28,8 +28,11 @@
 /**
  * SECTION:peas-extension
  * @short_description: Proxy for extensions.
+ * @see_also: #PeasExtensionSet
  *
- * A #PeasExtension is an object which proxies an actual extension.
+ * 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.
  **/
 
 G_DEFINE_ABSTRACT_TYPE (PeasExtension, peas_extension, G_TYPE_OBJECT);
@@ -48,6 +51,7 @@ peas_extension_class_init (PeasExtensionClass *klass)
  * peas_extension_call:
  * @exten: A #PeasExtension.
  * @method_name: the name of the method that should be called.
+ * @Varargs: arguments for the method.
  *
  * Call a method of the object behind @extension.
  *
@@ -68,6 +72,16 @@ peas_extension_call (PeasExtension *exten,
   return result;
 }
 
+/**
+ * peas_extension_call_valist:
+ * @exten: A #PeasExtension.
+ * @method_name: the name of the method that should be called.
+ * @args: the arguments for the method.
+ *
+ * Call a method of the object behind @extension, using @args as arguments.
+ *
+ * Return value: #TRUE on successful call.
+ */
 gboolean
 peas_extension_call_valist (PeasExtension *exten,
                             const gchar   *method_name,
diff --git a/libpeas/peas-extension.h b/libpeas/peas-extension.h
index 13b3290..4c5dc3b 100644
--- a/libpeas/peas-extension.h
+++ b/libpeas/peas-extension.h
@@ -64,10 +64,10 @@ struct _PeasExtensionClass {
 GType        peas_extension_get_type        (void)  G_GNUC_CONST;
 
 gboolean     peas_extension_call            (PeasExtension *exten,
-                                             const gchar   *method,
+                                             const gchar   *method_name,
                                              ...);
 gboolean     peas_extension_call_valist     (PeasExtension *exten,
-                                             const gchar   *method,
+                                             const gchar   *method_name,
                                              va_list        args);
 
 G_END_DECLS
diff --git a/libpeas/peas-object-module.c b/libpeas/peas-object-module.c
index 5dd5420..53cd955 100644
--- a/libpeas/peas-object-module.c
+++ b/libpeas/peas-object-module.c
@@ -28,6 +28,16 @@
 
 #include "peas-object-module.h"
 
+/**
+ * SECTION:peas-object-module
+ * @short_description: Type module which allows extension registration.
+ *
+ * #PeasObjectModule is a subclass of #GTypeModule which allows registration
+ * of extensions.  It will be used by C extensions implementors to register
+ * extension implementations from within the peas_register_types module
+ * function.
+ **/
+
 G_DEFINE_TYPE (PeasObjectModule, peas_object_module, G_TYPE_TYPE_MODULE);
 
 typedef void     (*PeasObjectModuleRegisterFunc) (PeasObjectModule *);
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]