docs: Move the GTypePlugin SECTION

Move the contents to the struct docs.

Helps: #3037
This commit is contained in:
Matthias Clasen 2023-09-25 15:24:31 -04:00 committed by Philip Withnall
parent 8009afe73d
commit bc084d8780
2 changed files with 22 additions and 31 deletions

View File

@ -23,10 +23,7 @@
/**
* SECTION:gtypeplugin
* @short_description: An interface for dynamically loadable types
* @see_also: #GTypeModule and g_type_register_dynamic().
* @title: GTypePlugin
* GTypePlugin:
*
* An interface that handles the lifecycle of dynamically loaded types.
*
@ -36,45 +33,45 @@
* 1. 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:
* |[<!-- language="C" -->
* ```c
* 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.
* `GTypePlugin` interface.
*
* 2. 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.
* [func@GObject.type_class_ref] or through [func@GObject.type_create_instance]
* (this is being called by [func@GObject.object_new]) or through one of the above
* done on a type derived from @new_type_id.
*
* 3. This causes the type system to load the type's implementation by
* calling g_type_plugin_use() and g_type_plugin_complete_type_info()
* 3. This causes the type system to load the type's implementation by calling
* [func@GObject.type_plugin_use] and [method@GObject.TypePlugin.complete_type_info]
* on @new_type_plugin.
*
* 4. 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).
*
* 4. At some point the type's implementation isn't required anymore, e.g. after
* [func@GObject.type_class_unref] or [func@GObject.type_free_instance]
* (called when the reference count of an instance drops to zero).
*
* 5. 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.
*
* from [method@GObject.TypePlugin.complete_type_info] and then it calls
* [method@GObject.TypePlugin.unuse] on @new_type_plugin.
*
* 6. Things may repeat from the second step.
*
* So basically, you need to implement a #GTypePlugin type that
* 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
* [method@GObject.TypePlugin.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.
* [method@GObject.TypePlugin.use] and [method@GObject.TypePlugin.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
* [struct@GObject.TypeModule] 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.
*/

View File

@ -80,12 +80,6 @@ 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.