Add /*< public >*/ and /*< private >*/ markers for documentation purposes.

Sat Oct 18 01:30:47 2003  Matthias Clasen  <maclas@gmx.de>

	* gtypeplugin.h (struct _GTypePluginClass): Add /*< public >*/
	and /*< private >*/ markers for documentation purposes.

	* gobject/tmpl/gboxed.sgml:
	* gobject/tmpl/gtypeplugin.sgml:
	* gobject/tmpl/enumerations_flags.sgml: Additions.

docs/reference/ChangeLog

@@ -1,3 +1,9 @@
+Sat Oct 18 01:30:47 2003  Matthias Clasen  <maclas@gmx.de>
+
+	* gobject/tmpl/gboxed.sgml: 
+	* gobject/tmpl/gtypeplugin.sgml: 
+	* gobject/tmpl/enumerations_flags.sgml: Additions.
+
 Sat Oct 18 00:04:22 2003  Matthias Clasen  <maclas@gmx.de>
 
 	* gobject/gobject.types: List GObject here, since the

docs/reference/gobject/tmpl/enumerations_flags.sgml

@@ -202,41 +202,80 @@ with that nickname
 
 <!-- ##### FUNCTION g_enum_register_static ##### -->
 <para>
-
+Registers a new static enumeration type with the name @name. 
+</para>
+<para>
+It is normally more convenient to let 
+<link linkend="glib-mkenums">glib-mkenums</link> generate a 
+my_enum_get_type() function from a usual C enumeration definition
+than to write one yourself using g_enum_register_static().
 </para>
 
-@name: 
+@name: A nul-terminated string used as the name of the new type.
-@const_static_values: 
+@const_static_values: An array of #GEnumValue structs for the possible
-@Returns: 
+  enumeration values. The array is terminated by a struct with all 
+  members being 0.
+@Returns: The new type identifier.
 
 
 <!-- ##### FUNCTION g_flags_register_static ##### -->
 <para>
-
+Registers a new static flags type with the name @name. 
+</para>
+<para>
+It is normally more convenient to let 
+<link linkend="glib-mkenums">glib-mkenums</link> generate a 
+my_flags_get_type() function from a usual C enumeration definition
+than to write one yourself using g_flags_register_static().
 </para>
 
-@name: 
+@name: A nul-terminated string used as the name of the new type.
-@const_static_values: 
+@const_static_values: An array of #GFlagsValue structs for the possible
-@Returns: 
+  flags values. The array is terminated by a struct with all members being 0.
+@Returns: The new type identifier.
 
 
 <!-- ##### FUNCTION g_enum_complete_type_info ##### -->
 <para>
-
+This function is meant to be called from the complete_type_info() function 
+of a #GTypePlugin implementation, as in the following example:
+<informalexample>
+<programlisting>
+static void
+my_enum_complete_type_info (GTypePlugin     *plugin,
+                            GType            g_type,
+                            GTypeInfo       *info,
+                            GTypeValueTable *value_table)
+{
+  static const GEnumValue values[] = {
+    { MY_ENUM_FOO, "MY_ENUM_FOO", "foo" },
+    { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" }
+  };  
+   
+  g_enum_complete_type_info (type, info, values);  
+}
+</programlisting>
+</informalexample>
 </para>
 
-@g_enum_type: 
+@g_enum_type: the type identifier of the type being completed
-@info: 
+@info: the #GTypeInfo struct to be filled in
-@const_values: 
+@const_values: An array of #GEnumValue structs for the possible
+  enumeration values. The array is terminated by a struct with all 
+  members being 0.
 
 
 <!-- ##### FUNCTION g_flags_complete_type_info ##### -->
 <para>
-
+This function is meant to be called from the complete_type_info() function 
+of a #GTypePlugin implementation, see the example for 
+g_enumeration_complete_type_info() above.
 </para>
 
-@g_flags_type: 
+@g_flags_type: the type identifier of the type being completed
-@info: 
+@info: the #GTypeInfo struct to be filled in
-@const_values: 
+@const_values: An array of #GFlagsValue structs for the possible
+  enumeration values. The array is terminated by a struct with all 
+  members being 0.
 
 

docs/reference/gobject/tmpl/gboxed.sgml

@@ -63,18 +63,16 @@ provided to copy and free opaque boxed structures of this type.
 @boxed_copy: Boxed structure copy function.
 @boxed_free: Boxed structure free function.
 @Returns: New %G_TYPE_BOXED derived type id for @name.
-<!-- # Unused Parameters # -->
-@boxed_init: 
-@is_refcounted: 
 
 
 <!-- ##### FUNCTION g_pointer_type_register_static ##### -->
 <para>
-
+Creates a new %G_TYPE_POINTER derived type id for a new
+pointer type with name @name. 
 </para>
 
-@name: 
+@name: the name of the new pointer type.
-@Returns: 
+@Returns: a new %G_TYPE_POINTER derived type id for @name.
 
 
 <!-- ##### MACRO G_TYPE_GSTRING ##### -->
@@ -84,3 +82,40 @@ The #GType for #GString.
 
 
 
+<!-- ##### MACRO G_TYPE_STRV ##### -->
+<para>
+The #GType for a boxed type holding a %NULL-terminated array of strings.
+</para>
+<para>
+The code fragments in the following example show the use of a property of
+type #G_TYPE_STRV with g_object_class_install_property(), g_object_set()
+and g_object_get().
+</para>
+<informalexample><programlisting>
+g_object_class_install_property (object_class,
+                                 PROP_AUTHORS,
+                                 g_param_spec_boxed ("authors",
+                                                     _("Authors"),
+                                                     _("List of authors"),
+                                                     G_TYPE_STRV,
+                                                     G_PARAM_READWRITE));
+
+
+gchar *authors[] = { "Owen", "Tim", NULL };
+g_object_set (obj, "authors", authors, NULL);
+
+
+gchar *writers[];
+g_object_get (obj, "authors", &amp;writers, NULL);
+/* do something with writers */
+g_strfreev (writers);
+</programlisting></informalexample>
+
+
+
+<!-- ##### TYPEDEF GStrv ##### -->
+<para>
+
+</para>
+
+

docs/reference/gobject/tmpl/gtypeplugin.sgml

@@ -6,12 +6,68 @@ An interface for dynamically loadable types
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+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:
+</para>
+<para>
+<orderedlist>
+<listitem><para>
+  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:
+<literal>new_type_id = g_type_register_dynamic (parent_type_id,
+                                                "TypeName",
+                                                new_type_plugin,
+                                                type_flags);
+</literal>
+  where <literal>new_type_plugin</literal> is an implementation of the
+  #GTypePlugin interface.
+</para></listitem>
+<listitem><para>  
+   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 <literal>new_type_id</literal>.
+</para></listitem>
+<listitem><para>  
+   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 
+   <literal>new_type_plugin</literal>.
+</para></listitem>
+<listitem><para>  
+   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).
+</para></listitem>
+<listitem><para>  
+   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 <literal>new_type_plugin</literal>.
+</para></listitem>
+<listitem><para>  
+   Things may repeat from the second step.
+</para></listitem>
+</orderedlist>
+</para>
+<para>
+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.
+</para>
+<para>
+#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.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#GTypeModule and g_type_register_dynamic().
 </para>
 
 <!-- ##### STRUCT GTypePlugin ##### -->
@@ -22,88 +78,105 @@ An interface for dynamically loadable types
 
 <!-- ##### STRUCT GTypePluginClass ##### -->
 <para>
-
+The #GTypePlugin interface is used by the type system in order to handle
+the lifecycle of dynamically loaded types.
 </para>
 
-@base_iface: 
+@use_plugin: Increases the use count of the plugin.
-@use_plugin: 
+@unuse_plugin: Decreases the use count of the plugin.
-@unuse_plugin: 
+@complete_type_info: Fills in the #GTypeInfo and 
-@complete_type_info: 
+  #GTypeValueTable structs for the type. The structs are initialized
-@complete_interface_info: 
+  with <literal>memset(s, 0, sizeof (s))</literal> before calling 
+  this function.
+@complete_interface_info: Fills in missing parts of the #GInterfaceInfo 
+  for the interface. The structs is initialized with 
+  <literal>memset(s, 0, sizeof (s))</literal> before calling
+  this function.
 
 <!-- ##### USER_FUNCTION GTypePluginUse ##### -->
 <para>
-
+The type of the @use_plugin function of #GTypePluginClass, which gets called
+to increase the use count of @plugin.
 </para>
 
-@plugin: 
+@plugin: the #GTypePlugin whose use count should be increased
 
 
 <!-- ##### USER_FUNCTION GTypePluginUnuse ##### -->
 <para>
-
+The type of the @unuse_plugin function of #GTypePluginClass.
 </para>
 
-@plugin: 
+@plugin: the #GTypePlugin whose use count should be decreased
 
 
 <!-- ##### USER_FUNCTION GTypePluginCompleteTypeInfo ##### -->
 <para>
-
+The type of the @complete_type_info function of #GTypePluginClass.
 </para>
 
-@plugin: 
+@plugin: the #GTypePlugin
-@g_type: 
+@g_type: the #GType whose info is completed
-@info: 
+@info: the #GTypeInfo struct to fill in
-@value_table: 
+@value_table: the #GTypeValueTable to fill in
 
 
 <!-- ##### USER_FUNCTION GTypePluginCompleteInterfaceInfo ##### -->
 <para>
-
+The type of the @complete_interface_info function of #GTypePluginClass.
 </para>
 
-@plugin: 
+@plugin: the #GTypePlugin
-@instance_type: 
+@instance_type: the #GType of an instantiable type to which the interface
-@interface_type: 
+  is added
-@info: 
+@interface_type: the #GType of the interface whose info is completed
+@info: the #GInterfaceInfo to fill in
 
 
 <!-- ##### FUNCTION g_type_plugin_use ##### -->
 <para>
-
+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.
 </para>
 
-@plugin: 
+@plugin: a #GTypePlugin
 
 
 <!-- ##### FUNCTION g_type_plugin_unuse ##### -->
 <para>
-
+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.
 </para>
 
-@plugin: 
+@plugin: a #GTypePlugin
 
 
 <!-- ##### FUNCTION g_type_plugin_complete_type_info ##### -->
 <para>
-
+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.
 </para>
 
-@plugin: 
+@plugin: a #GTypePlugin
-@g_type: 
+@g_type: the #GType whose info is completed
-@info: 
+@info: the #GTypeInfo struct to fill in
-@value_table: 
+@value_table: the #GTypeValueTable to fill in
 
 
 <!-- ##### FUNCTION g_type_plugin_complete_interface_info ##### -->
 <para>
-
+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.
 </para>
 
-@plugin: 
+@plugin: the #GTypePlugin
-@instance_type: 
+@instance_type: the #GType of an instantiable type to which the interface
-@interface_type: 
+  is added
-@info: 
+@interface_type: the #GType of the interface whose info is completed
+@info: the #GInterfaceInfo to fill in
 
 

gobject/ChangeLog

@@ -1,3 +1,8 @@
+Sat Oct 18 01:24:14 2003  Matthias Clasen  <maclas@gmx.de>
+
+	* gtypeplugin.h (struct _GTypePluginClass): Add /*< public >*/
+	and /*< private >*/ markers for documentation purposes.
+
 Thu Oct  2 07:37:12 2003  Tim Janik  <timj@gtk.org>
 
 	* gtype.c: fix post class_init interface initialization logic

gobject/gtypeplugin.h

@@ -50,8 +50,10 @@ typedef void  (*GTypePluginCompleteInterfaceInfo) (GTypePlugin     *plugin,
 						   GInterfaceInfo  *info);
 struct _GTypePluginClass
 {
+  /*< private >*/
   GTypeInterface		   base_iface;
   
+  /*< public >*/
   GTypePluginUse		   use_plugin;
   GTypePluginUnuse		   unuse_plugin;
   GTypePluginCompleteTypeInfo	   complete_type_info;