libgimpmodule/libgimpmodule-sections.txt

2003-01-02  Michael Natterer  <mitch@gimp.org>

	* libgimpmodule/libgimpmodule-sections.txt
	* libgimpmodule/tmpl/gimpmodule.sgml
	* libgimpmodule/tmpl/gimpmoduledb.sgml: updated. Documented
	enums and structs. Fixes bug #5746.

devel-docs/ChangeLog

+2003-01-02  Michael Natterer  <mitch@gimp.org>
+
+	* libgimpmodule/libgimpmodule-sections.txt
+	* libgimpmodule/tmpl/gimpmodule.sgml
+	* libgimpmodule/tmpl/gimpmoduledb.sgml: updated. Documented
+	enums and structs. Fixes bug #5746.
+
 2003-01-02  Michael Natterer  <mitch@gimp.org>
 
 	* libgimpmodule/tmpl/gimpmodule.sgml: regenerated, removed

devel-docs/libgimpmodule/libgimpmodule-sections.txt

@@ -5,6 +5,7 @@ GimpModuleInfo
 GimpModuleState
 GimpModuleQueryFunc
 GimpModuleRegisterFunc
+GIMP_MODULE_ABI_VERSION
 <TITLE>GimpModule</TITLE>
 gimp_module_new
 gimp_module_modified

devel-docs/libgimpmodule/tmpl/gimpmodule.sgml

@@ -2,11 +2,11 @@
 GimpModule
 
 <!-- ##### SECTION Short_Description ##### -->
-Common definitions for creating a pluggable GIMP module.
+A #GTypeModule subclass which implements module loading using #GModule.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-Common definitions for creating a pluggable GIMP module.
+A #GTypeModule subclass which implements module loading using #GModule.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -19,48 +19,86 @@ Common definitions for creating a pluggable GIMP module.
 
 <!-- ##### STRUCT GimpModule ##### -->
 <para>
-
+#GimpModule is a generic mechanism to dynamically load modules into
+the GIMP.  It is a #GTypeModule subclass, implementing module loading
+using #GModule.  #GimpModule does not know which functionality is
+implemented by the modules, it just provides a framework to get
+arbitrary #GType implementations loaded from disk.
 </para>
 
+@filename: 
+@verbose: 
+@state: 
+@on_disk: 
+@load_inhibit: 
+@info: 
+@last_module_error: 
 
 <!-- ##### STRUCT GimpModuleInfo ##### -->
 <para>
-
+This structure contains information about a loadable module.
 </para>
 
-@abi_version: 
-@purpose: 
-@author: 
-@version: 
-@copyright: 
-@date: 
+@abi_version: The #GIMP_MODULE_ABI_VERSION the module was compiled against.
+@purpose:     The module's general purpose.
+@author:      The module's author.
+@version:     The module's version.
+@copyright:   The module's copyright.
+@date:        The module's release date.
 
 <!-- ##### ENUM GimpModuleState ##### -->
 <para>
-
+The possible states a #GimpModule can be in.
 </para>
 
-@GIMP_MODULE_STATE_ERROR: 
-@GIMP_MODULE_STATE_LOADED: 
-@GIMP_MODULE_STATE_LOAD_FAILED: 
-@GIMP_MODULE_STATE_NOT_LOADED: 
+@GIMP_MODULE_STATE_ERROR:       Missing gimp_module_register() function
+                                or other error.
+@GIMP_MODULE_STATE_LOADED:      An instance of a type implemented by
+                                this module is allocated.
+@GIMP_MODULE_STATE_LOAD_FAILED: gimp_module_register() returned #FALSE.
+@GIMP_MODULE_STATE_NOT_LOADED:  There are no instances allocated of
+                                types implemented by this module.
 
 <!-- ##### USER_FUNCTION GimpModuleQueryFunc ##### -->
 <para>
+The signature of the query function a loadable GIMP module must
+implement.  In the module, the function must be called
+gimp_module_query().
+</para>
 
+<para>
+#GimpModule will copy the returned #GimpModuleInfo struct, so the
+module doesn't need to keep these values around (however in most cases
+the module will just return a pointer to a constant structure).
 </para>
 
-@module: 
-@Returns: 
+@module:  The #GimpModule responsible for this loadable module.
+@Returns: The #GimpModuleInfo struct describing the module.
 
 
 <!-- ##### USER_FUNCTION GimpModuleRegisterFunc ##### -->
 <para>
+The signature of the register function a loadable GIMP module must
+implement.  In the module, the function must be called
+gimp_module_register().
+</para>
 
+<para>
+When this function is called, the module should register all the types
+it implements with the passed @module.
 </para>
 
-@module: 
-@Returns: 
+@module:  The #GimpModule responsible for this loadable module.
+@Returns: #TRUE on success, #FALSE otherwise.
+
+
+<!-- ##### MACRO GIMP_MODULE_ABI_VERSION ##### -->
+<para>
+The version of the module system's ABI. Modules put this value into
+#GimpModuleInfo's @abi_version field so the code loading the modules
+can check if it was compiled against the same module ABI the modules
+are compiled against.
+</para>
 
 
 <!-- ##### FUNCTION gimp_module_new ##### -->

devel-docs/libgimpmodule/tmpl/gimpmoduledb.sgml

@@ -2,11 +2,11 @@
 GimpModuleDB
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Keeps a list of #GimpModule's found in a given searchpath.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+Keeps a list of #GimpModule's found in a given searchpath.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -16,7 +16,7 @@ GimpModuleDB
 
 <!-- ##### STRUCT GimpModuleDB ##### -->
 <para>
-
+The #GimpModuleDB struct contains no public members.
 </para>