glib r7077 - in trunk: . docs/reference/gobject/tmpl gobject

[stefkost svn gnome org]

Author: stefkost
Date: Sat Jun 21 16:35:50 2008
New Revision: 7077
URL: http://svn.gnome.org/viewvc/glib?rev=7077&view=rev

Log:
	* docs/reference/gobject/tmpl/gtypemodule.sgml:
	* gobject/gtypemodule.c:
	* gobject/gtypemodule.h:
	  Migrating docs.



Removed:
   trunk/docs/reference/gobject/tmpl/gtypemodule.sgml
Modified:
   trunk/ChangeLog
   trunk/docs/reference/gobject/tmpl/   (props changed)
   trunk/gobject/gtypemodule.c
   trunk/gobject/gtypemodule.h

Modified: trunk/gobject/gtypemodule.c
==============================================================================
--- trunk/gobject/gtypemodule.c	(original)
+++ trunk/gobject/gtypemodule.c	Sat Jun 21 16:35:50 2008
@@ -16,6 +16,49 @@
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  * Boston, MA 02111-1307, USA.
  */
+/**
+ * SECTION:gtypemodule
+ * @Short_description: Type loading modules
+ * @See_also:<variablelist>
+ * <varlistentry>
+ * <term>#GTypePlugin</term>
+ * <listitem><para>The abstract type loader interface.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>#GModule</term>
+ * <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem>
+ * </varlistentry>
+ * </variablelist>
+ * @Title: GTypeModule
+ * 
+ * #GTypeModule provides a simple implementation of the #GTypePlugin
+ * interface. The model of #GTypeModule is a dynamically loaded module
+ * which implements some number of types and interface
+ * implementations. When the module is loaded, it registers its types
+ * and interfaces using g_type_module_register_type() and
+ * g_type_module_add_interface().  As long as any instances of these
+ * types and interface implementations are in use, the module is kept
+ * loaded. When the types and interfaces are gone, the module may be
+ * unloaded. If the types and interfaces become used again, the module
+ * will be reloaded. Note that the last unref can not happen in module
+ * code, since that would lead to the caller's code being unloaded before
+ * g_object_unref() returns to it.
+ * 
+ * Keeping track of whether the module should be loaded or not is done by
+ * using a use count - it starts at zero, and whenever it is greater than
+ * zero, the module is loaded. The use count is maintained internally by
+ * the type system, but also can be explicitly controlled by
+ * g_type_module_use() and g_type_module_unuse(). Typically, when loading
+ * a module for the first type, g_type_module_use() will be used to load
+ * it so that it can initialize its types. At some later point, when the
+ * module no longer needs to be loaded except for the type
+ * implementations it contains, g_type_module_unuse() is called.
+ * 
+ * #GTypeModule does not actually provide any implementation of module
+ * loading and unloading. To create a particular module type you must
+ * derive from #GTypeModule and implement the load and unload functions
+ * in #GTypeModuleClass.
+ */
 
 #include <stdlib.h>
 
@@ -131,6 +174,13 @@
   return type_module_type;
 }
 
+/**
+ * g_type_module_set_name:
+ * @module: a #GTypeModule.
+ * @name: a human-readable name to use in error messages.
+ * 
+ * Sets the name for a #GTypeModule 
+ */
 void
 g_type_module_set_name (GTypeModule  *module,
 			const gchar  *name)
@@ -177,6 +227,16 @@
   return NULL;
 }
 
+/**
+ * g_type_module_use:
+ * @module: a #GTypeModule
+ * 
+ * Increases the use count of a #GTypeModule by one. If the
+ * use count was zero before, the plugin will be loaded.
+ * 
+ * Returns: %FALSE if the plugin needed to be loaded and
+ *  loading the plugin failed.
+ */
 gboolean
 g_type_module_use (GTypeModule *module)
 {
@@ -212,6 +272,16 @@
   return TRUE;
 }
 
+/**
+ * g_type_module_unuse:
+ * @module: a #GTypeModule
+ * 
+ * Decreases the use count of a #GTypeModule by one. If the
+ * result is zero, the module will be unloaded. (However, the
+ * #GTypeModule will not be freed, and types associated with the
+ * #GTypeModule are not unregistered. Once a #GTypeModule is 
+ * initialized, it must exist forever.)
+ */
 void
 g_type_module_unuse (GTypeModule *module)
 {
@@ -277,6 +347,28 @@
   *info = module_interface_info->info;
 }
 
+/**
+ * g_type_module_register_type:
+ * @module: a #GTypeModule
+ * @parent_type: the type for the parent class
+ * @type_name: name for the type
+ * @type_info: type information structure
+ * @flags: flags field providing details about the type
+ * 
+ * Looks up or registers a type that is implemented with a particular
+ * type plugin. If a type with name @type_name was previously registered,
+ * the #GType identifier for the type is returned, otherwise the type
+ * is newly registered, and the resulting #GType identifier returned.
+ * 
+ * When reregistering a type (typically because a module is unloaded
+ * then reloaded, and reinitialized), @module and @parent_type must
+ * be the same as they were previously.
+ * 
+ * As long as any instances of the type exist, the type plugin will
+ * not be unloaded.
+ * 
+ * Returns: the new or existing type ID
+ */
 GType
 g_type_module_register_type (GTypeModule     *module,
 			     GType            parent_type,
@@ -340,6 +432,20 @@
   return module_type_info->type;
 }
 
+/**
+ * g_type_module_add_interface:
+ * @module: a #GTypeModule
+ * @instance_type: type to which to add the interface.
+ * @interface_type: interface type to add
+ * @interface_info: type information structure
+ * 
+ * Registers an additional interface for a type, whose interface
+ * lives in the given type plugin. If the interface was already registered
+ * for the type in this plugin, nothing will be done. 
+ * 
+ * As long as any instances of the type exist, the type plugin will
+ * not be unloaded.
+ */
 void
 g_type_module_add_interface (GTypeModule          *module,
 			     GType                 instance_type,
@@ -389,6 +495,25 @@
   module_interface_info->info = *interface_info;
 }
 
+/**
+ * g_type_module_register_enum:
+ * @module: a #GTypeModule
+ * @name: name for the type
+ * @const_static_values: an array of #GEnumValue structs for the possible
+ *  enumeration values. The array is terminated by a struct with all 
+ *  members being 0.
+ * 
+ * Looks up or registers an enumeration that is implemented with a particular
+ * type plugin. If a type with name @type_name was previously registered,
+ * the #GType identifier for the type is returned, otherwise the type
+ * is newly registered, and the resulting #GType identifier returned.
+ * 
+ * As long as any instances of the type exist, the type plugin will
+ * not be unloaded.
+ * 
+ * Since: 2.6
+ * Returns: the new or existing type ID
+ */
 GType
 g_type_module_register_enum (GTypeModule      *module,
                              const gchar      *name,
@@ -407,6 +532,25 @@
                                       G_TYPE_ENUM, name, &enum_type_info, 0);
 }
 
+/**
+ * g_type_module_register_flags:
+ * @module: a #GTypeModule
+ * @name: name for the type
+ * @const_static_values: an array of #GFlagsValue structs for the possible
+ *  flags values. The array is terminated by a struct with all 
+ *  members being 0.
+ * 
+ * Looks up or registers a flags type that is implemented with a particular
+ * type plugin. If a type with name @type_name was previously registered,
+ * the #GType identifier for the type is returned, otherwise the type
+ * is newly registered, and the resulting #GType identifier returned.
+ * 
+ * As long as any instances of the type exist, the type plugin will
+ * not be unloaded.
+ * 
+ * Since: 2.6
+ * Returns: the new or existing type ID
+ */
 GType
 g_type_module_register_flags (GTypeModule      *module,
                              const gchar       *name,

Modified: trunk/gobject/gtypemodule.h
==============================================================================
--- trunk/gobject/gtypemodule.h	(original)
+++ trunk/gobject/gtypemodule.h	Sat Jun 21 16:35:50 2008
@@ -38,6 +38,13 @@
 #define G_IS_TYPE_MODULE_CLASS(class)   (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_TYPE_MODULE))
 #define G_TYPE_MODULE_GET_CLASS(module) (G_TYPE_INSTANCE_GET_CLASS ((module), G_TYPE_TYPE_MODULE, GTypeModuleClass))
 
+/**
+ * GTypeModule:
+ * @name: the name of the module
+ * 
+ * The members of the <structname>GTypeModule</structname> structure should not 
+ * be accessed directly, except for the @name field.
+ */
 struct _GTypeModule 
 {
   GObject parent_instance;
@@ -50,6 +57,16 @@
   gchar *name;
 };
 
+/**
+ * GTypeModuleClass:
+ * @parent_class: the parent class
+ * @load: loads the module and registers one or more types using
+ *  g_type_module_register_type().
+ * @unload: unloads the module
+ * 
+ * In order to implement dynamic loading of types based on #GTypeModule, 
+ * the @load and @unload functions in #GTypeModuleClass must be implemented.
+ */
 struct _GTypeModuleClass
 {
   GObjectClass parent_class;
@@ -66,7 +83,97 @@
   void (*reserved4) (void);
 };
 
+/**
+ * G_DEFINE_DYNAMIC_TYPE:
+ * @TN: The name of the new type, in Camel case.
+ * @t_n: The name of the new type, in lowercase, with words
+ *  separated by '_'.
+ * @T_P: The #GType of the parent type.
+ * 
+ * A convenience macro for dynamic type implementations, which declares a
+ * class initialization function, an instance initialization function (see 
+ * #GTypeInfo for information about these) and a static variable named 
+ * @t_n<!-- -->_parent_class pointing to the parent class. Furthermore, 
+ * it defines a <function>*_get_type()</function> and a static 
+ * <function>*_register_type()</function> function for use in your
+ * <function>module_init()</function>.
+ * See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example.
+ * 
+ * Since: 2.14
+ */
 #define G_DEFINE_DYNAMIC_TYPE(TN, t_n, T_P)          G_DEFINE_DYNAMIC_TYPE_EXTENDED (TN, t_n, T_P, 0, {})
+/**
+ * G_DEFINE_DYNAMIC_TYPE_EXTENDED:
+ * @TypeName: The name of the new type, in Camel case.
+ * @type_name: The name of the new type, in lowercase, with words
+ *  separated by '_'.
+ * @TYPE_PARENT: The #GType of the parent type.
+ * @flags: #GTypeFlags to pass to g_type_module_register_type()
+ * @CODE: Custom code that gets inserted in the *_get_type() function.
+ * 
+ * A more general version of G_DEFINE_DYNAMIC_TYPE() which
+ * allows to specify #GTypeFlags and custom code.
+ * 
+ * |[
+ * G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget,
+ *                                 gtk_gadget,
+ *                                 GTK_TYPE_THING,
+ *                                 0,
+ *                                 G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
+ *                                                        gtk_gadget_gizmo_init));
+ * ]|
+ * expands to
+ * |[
+ * static void     gtk_gadget_init              (GtkGadget      *self);
+ * static void     gtk_gadget_class_init        (GtkGadgetClass *klass);
+ * static void     gtk_gadget_class_finalize    (GtkGadgetClass *klass);
+ * 
+ * static gpointer gtk_gadget_parent_class = NULL;
+ * static GType    gtk_gadget_type_id = 0;
+ * 
+ * static void     gtk_gadget_class_intern_init (gpointer klass)
+ * {
+ *   gtk_gadget_parent_class = g_type_class_peek_parent (klass); 
+ *   gtk_gadget_class_init ((GtkGadgetClass*) klass); 
+ * }
+ * 
+ * GType
+ * gtk_gadget_get_type (void)
+ * {
+ *   return gtk_gadget_type_id;
+ * }
+ * 
+ * static void
+ * gtk_gadget_register_type (GTypeModule *type_module)
+ * {
+ *   const GTypeInfo g_define_type_info = {
+ *     sizeof (GtkGadgetClass),
+ *     (GBaseInitFunc) NULL,
+ *     (GBaseFinalizeFunc) NULL,
+ *     (GClassInitFunc) gtk_gadget_class_intern_init,
+ *     (GClassFinalizeFunc) gtk_gadget_class_finalize,
+ *     NULL,   // class_data
+ *     sizeof (GtkGadget),
+ *     0,      // n_preallocs
+ *     (GInstanceInitFunc) gtk_gadget_init, 
+ *     NULL    // value_table
+ *   };
+ *   gtk_gadget_type_id = g_type_module_register_type (type_module,
+ *                                                     GTK_TYPE_THING,
+ *                                                     GtkGadget,
+ *                                                     &g_define_type_info,
+ *                                                     (GTypeFlags) flags);
+ *   {
+ *     const GInterfaceInfo g_implement_interface_info = {
+ *       (GInterfaceInitFunc) gtk_gadget_gizmo_init
+ *     };
+ *     g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
+ *   }
+ * }
+ * ]|
+ * 
+ * Since: 2.14
+ */
 #define G_DEFINE_DYNAMIC_TYPE_EXTENDED(TypeName, type_name, TYPE_PARENT, flags, CODE) \
 static void     type_name##_init              (TypeName        *self); \
 static void     type_name##_class_init        (TypeName##Class *klass); \