From: Stefan Kost Date: Sat, 21 Jun 2008 18:20:43 +0000 (+0000) Subject: Migrating docs. X-Git-Tag: GLIB_2_17_3~51 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=3f5419f6f166e20d42ce6222f58110e93347c3f5;p=platform%2Fupstream%2Fglib.git Migrating docs. * docs/reference/gobject/tmpl/gtypeplugin.sgml: * gobject/gtypeplugin.c: * gobject/gtypeplugin.h: Migrating docs. svn path=/trunk/; revision=7079 --- diff --git a/ChangeLog b/ChangeLog index 05b3a33..d5bdbab 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,12 @@ 2008-06-21 Stefan Kost + * docs/reference/gobject/tmpl/gtypeplugin.sgml: + * gobject/gtypeplugin.c: + * gobject/gtypeplugin.h: + Migrating docs. + +2008-06-21 Stefan Kost + * docs/reference/gobject/Makefile.am: Add --sgml-mode to allow sgml in doc-fragments (which somehow works before already). @@ -9,7 +16,7 @@ * gobject/gparam.c: * gobject/gparam.h: * gobject/gtype.h: - Convert character entities back. FIx some broken sgml. + Convert character entities back. Fix some broken sgml. 2008-06-21 Stefan Kost diff --git a/docs/reference/gobject/tmpl/gtypeplugin.sgml b/docs/reference/gobject/tmpl/gtypeplugin.sgml deleted file mode 100644 index 07b535f..0000000 --- a/docs/reference/gobject/tmpl/gtypeplugin.sgml +++ /dev/null @@ -1,187 +0,0 @@ - -GTypePlugin - - -An interface for dynamically loadable types - - - -The GObject type system supports dynamic loading of types. The #GTypePlugin -interface is used to handle the lifecycle of dynamically loaded types. -It goes as follows: - - - - - The type is initially introduced (usually upon loading the module - the first time, or by your main application that knows what modules - introduces what types), like this: -new_type_id = g_type_register_dynamic (parent_type_id, - "TypeName", - new_type_plugin, - type_flags); - - where new_type_plugin is an implementation of the - #GTypePlugin interface. - - - The type's implementation is referenced, e.g. through - g_type_class_ref() or through g_type_create_instance() (this is - being called by g_object_new()) or through one of the above done on - a type derived from new_type_id. - - - This causes the type system to load the type's implementation by calling - g_type_plugin_use() and g_type_plugin_complete_type_info() on - new_type_plugin. - - - At some point the type's implementation isn't required anymore, e.g. after - g_type_class_unref() or g_type_free_instance() (called when the reference - count of an instance drops to zero). - - - This causes the type system to throw away the information retrieved from - g_type_plugin_complete_type_info() and then it calls - g_type_plugin_unuse() on new_type_plugin. - - - Things may repeat from the second step. - - - - -So basically, you need to implement a #GTypePlugin type that carries a -use_count, once use_count goes from zero to one, you need to load the -implementation to successfully handle the upcoming -g_type_plugin_complete_type_info() call. Later, maybe after succeeding -use/unuse calls, once use_count drops to zero, you can unload the -implementation again. The type system makes sure to call g_type_plugin_use() -and g_type_plugin_complete_type_info() again when the type is needed again. - - -#GTypeModule is an implementation of #GTypePlugin that already implements -most of this except for the actual module loading and unloading. It even -handles multiple registered types per module. - - - - -#GTypeModule and g_type_register_dynamic(). - - - - - - - -The GTypePlugin typedef is used as a placeholder -for objects that implement the GTypePlugin -interface. - - - - - -The #GTypePlugin interface is used by the type system in order to handle -the lifecycle of dynamically loaded types. - - -@use_plugin: Increases the use count of the plugin. -@unuse_plugin: Decreases the use count of the plugin. -@complete_type_info: Fills in the #GTypeInfo and - #GTypeValueTable structs for the type. The structs are initialized - with memset(s, 0, sizeof (s)) before calling - this function. -@complete_interface_info: Fills in missing parts of the #GInterfaceInfo - for the interface. The structs is initialized with - memset(s, 0, sizeof (s)) before calling - this function. - - - -The type of the @use_plugin function of #GTypePluginClass, which gets called -to increase the use count of @plugin. - - -@plugin: the #GTypePlugin whose use count should be increased - - - - -The type of the @unuse_plugin function of #GTypePluginClass. - - -@plugin: the #GTypePlugin whose use count should be decreased - - - - -The type of the @complete_type_info function of #GTypePluginClass. - - -@plugin: the #GTypePlugin -@g_type: the #GType whose info is completed -@info: the #GTypeInfo struct to fill in -@value_table: the #GTypeValueTable to fill in - - - - -The type of the @complete_interface_info function of #GTypePluginClass. - - -@plugin: the #GTypePlugin -@instance_type: the #GType of an instantiable type to which the interface - is added -@interface_type: the #GType of the interface whose info is completed -@info: the #GInterfaceInfo to fill in - - - - -Calls the @use_plugin function from the #GTypePluginClass of @plugin. -There should be no need to use this function outside of the GObject -type system itself. - - -@plugin: a #GTypePlugin - - - - -Calls the @unuse_plugin function from the #GTypePluginClass of @plugin. -There should be no need to use this function outside of the GObject -type system itself. - - -@plugin: a #GTypePlugin - - - - -Calls the @complete_type_info function from the #GTypePluginClass of @plugin. -There should be no need to use this function outside of the GObject -type system itself. - - -@plugin: a #GTypePlugin -@g_type: the #GType whose info is completed -@info: the #GTypeInfo struct to fill in -@value_table: the #GTypeValueTable to fill in - - - - -Calls the @complete_interface_info function from the #GTypePluginClass -of @plugin. There should be no need to use this function outside of the -GObject type system itself. - - -@plugin: the #GTypePlugin -@instance_type: the #GType of an instantiable type to which the interface - is added -@interface_type: the #GType of the interface whose info is completed -@info: the #GInterfaceInfo to fill in - - diff --git a/gobject/gtypeplugin.c b/gobject/gtypeplugin.c index 2d681bd..8aaa7e4 100644 --- a/gobject/gtypeplugin.c +++ b/gobject/gtypeplugin.c @@ -16,6 +16,68 @@ * Free Software Foundation, Inc., 59 Temple Place, Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION:gtypeplugin + * @Short_description: An interface for dynamically loadable types + * @See_also:#GTypeModule and g_type_register_dynamic(). + * @Titile: GTypePlugin + * + * The GObject type system supports dynamic loading of types. The #GTypePlugin + * interface is used to handle the lifecycle of dynamically loaded types. + * It goes as follows: + * + * + * + * The type is initially introduced (usually upon loading the module + * the first time, or by your main application that knows what modules + * introduces what types), like this: + * |[ + * new_type_id = g_type_register_dynamic (parent_type_id, + * "TypeName", + * new_type_plugin, + * type_flags); + * ]| + * where new_type_plugin is an implementation of the + * #GTypePlugin interface. + * + * + * The type's implementation is referenced, e.g. through + * g_type_class_ref() or through g_type_create_instance() (this is + * being called by g_object_new()) or through one of the above done on + * a type derived from new_type_id. + * + * + * This causes the type system to load the type's implementation by calling + * g_type_plugin_use() and g_type_plugin_complete_type_info() on + * new_type_plugin. + * + * + * At some point the type's implementation isn't required anymore, e.g. after + * g_type_class_unref() or g_type_free_instance() (called when the reference + * count of an instance drops to zero). + * + * + * This causes the type system to throw away the information retrieved from + * g_type_plugin_complete_type_info() and then it calls + * g_type_plugin_unuse() on new_type_plugin. + * + * + * Things may repeat from the second step. + * + * + * + * So basically, you need to implement a #GTypePlugin type that carries a + * use_count, once use_count goes from zero to one, you need to load the + * implementation to successfully handle the upcoming + * g_type_plugin_complete_type_info() call. Later, maybe after succeeding + * use/unuse calls, once use_count drops to zero, you can unload the + * implementation again. The type system makes sure to call g_type_plugin_use() + * and g_type_plugin_complete_type_info() again when the type is needed again. + * + * #GTypeModule is an implementation of #GTypePlugin that already implements + * most of this except for the actual module loading and unloading. It even + * handles multiple registered types per module. + */ #include "gtypeplugin.h" #include "gobjectalias.h" @@ -41,6 +103,14 @@ g_type_plugin_get_type (void) return type_plugin_type; } +/** + * g_type_plugin_use: + * @plugin: a #GTypePlugin + * + * Calls the @use_plugin function from the #GTypePluginClass of @plugin. + * There should be no need to use this function outside of the GObject + * type system itself. + */ void g_type_plugin_use (GTypePlugin *plugin) { @@ -52,6 +122,14 @@ g_type_plugin_use (GTypePlugin *plugin) iface->use_plugin (plugin); } +/** + * g_type_plugin_unuse: + * @plugin: a #GTypePlugin + * + * Calls the @unuse_plugin function from the #GTypePluginClass of @plugin. + * There should be no need to use this function outside of the GObject + * type system itself. + */ void g_type_plugin_unuse (GTypePlugin *plugin) { @@ -63,6 +141,17 @@ g_type_plugin_unuse (GTypePlugin *plugin) iface->unuse_plugin (plugin); } +/** + * g_type_plugin_complete_type_info: + * @plugin: a #GTypePlugin + * @g_type: the #GType whose info is completed + * @info: the #GTypeInfo struct to fill in + * @value_table: the #GTypeValueTable to fill in + * + * Calls the @complete_type_info function from the #GTypePluginClass of @plugin. + * There should be no need to use this function outside of the GObject + * type system itself. + */ void g_type_plugin_complete_type_info (GTypePlugin *plugin, GType g_type, @@ -82,6 +171,18 @@ g_type_plugin_complete_type_info (GTypePlugin *plugin, value_table); } +/** + * g_type_plugin_complete_interface_info: + * @plugin: the #GTypePlugin + * @instance_type: the #GType of an instantiable type to which the interface + * is added + * @interface_type: the #GType of the interface whose info is completed + * @info: the #GInterfaceInfo to fill in + * + * Calls the @complete_interface_info function from the #GTypePluginClass + * of @plugin. There should be no need to use this function outside of the + * GObject type system itself. + */ void g_type_plugin_complete_interface_info (GTypePlugin *plugin, GType instance_type, diff --git a/gobject/gtypeplugin.h b/gobject/gtypeplugin.h index a8e9803..ff87a70 100644 --- a/gobject/gtypeplugin.h +++ b/gobject/gtypeplugin.h @@ -38,16 +38,71 @@ G_BEGIN_DECLS /* --- typedefs & structures --- */ typedef struct _GTypePluginClass GTypePluginClass; +/** + * GTypePluginUse: + * @plugin: the #GTypePlugin whose use count should be increased + * + * The type of the @use_plugin function of #GTypePluginClass, which gets called + * to increase the use count of @plugin. + */ typedef void (*GTypePluginUse) (GTypePlugin *plugin); +/** + * GTypePluginUnuse: + * @plugin: the #GTypePlugin whose use count should be decreased + * + * The type of the @unuse_plugin function of #GTypePluginClass. + */ typedef void (*GTypePluginUnuse) (GTypePlugin *plugin); +/** + * GTypePluginCompleteTypeInfo: + * @plugin: the #GTypePlugin + * @g_type: the #GType whose info is completed + * @info: the #GTypeInfo struct to fill in + * @value_table: the #GTypeValueTable to fill in + * + * The type of the @complete_type_info function of #GTypePluginClass. + */ typedef void (*GTypePluginCompleteTypeInfo) (GTypePlugin *plugin, GType g_type, GTypeInfo *info, GTypeValueTable *value_table); +/** + * GTypePluginCompleteInterfaceInfo: + * @plugin: the #GTypePlugin + * @instance_type: the #GType of an instantiable type to which the interface + * is added + * @interface_type: the #GType of the interface whose info is completed + * @info: the #GInterfaceInfo to fill in + * + * The type of the @complete_interface_info function of #GTypePluginClass. + */ typedef void (*GTypePluginCompleteInterfaceInfo) (GTypePlugin *plugin, GType instance_type, GType interface_type, GInterfaceInfo *info); +/** + * GTypePlugin: + * + * The GTypePlugin typedef is used as a placeholder + * for objects that implement the GTypePlugin + * interface. + */ +/** + * GTypePluginClass: + * @use_plugin: Increases the use count of the plugin. + * @unuse_plugin: Decreases the use count of the plugin. + * @complete_type_info: Fills in the #GTypeInfo and + * #GTypeValueTable structs for the type. The structs are initialized + * with memset(s, 0, sizeof (s)) before calling + * this function. + * @complete_interface_info: Fills in missing parts of the #GInterfaceInfo + * for the interface. The structs is initialized with + * memset(s, 0, sizeof (s)) before calling + * this function. + * + * The #GTypePlugin interface is used by the type system in order to handle + * the lifecycle of dynamically loaded types. + */ struct _GTypePluginClass { /*< private >*/