libgimpmodule/gimpmodule.[ch] added API docs, removed cruft. Fixes bug

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

	* libgimpmodule/gimpmodule.[ch]
	* libgimpmodule/gimpmoduledb.[ch]: added API docs, removed cruft.
	Fixes bug #5746.

ChangeLog

@@ -1,3 +1,9 @@
+2003-01-02  Michael Natterer  <mitch@gimp.org>
+
+	* libgimpmodule/gimpmodule.[ch]
+	* libgimpmodule/gimpmoduledb.[ch]: added API docs, removed cruft.
+	Fixes bug #5746.
+
 2003-01-02  Maurits Rijk  <lpeek.mrijk@consunet.nl>
 
 	* plug-ins/imagemap/imap_preview.[ch]: fix for #102303

libgimpmodule/gimpmodule.c

@@ -233,6 +233,16 @@ gimp_module_unload (GTypeModule *module)
 
 /*  public functions  */
 
+/**
+ * gimp_module_new:
+ * @filename:     The filename of a loadable module.
+ * @load_inhibit: Pass #TRUE to exclude this module from auto-loading.
+ * @verbose:      Pass #TRUE to enable debugging output.
+ * 
+ * Creates a new #GimpModule instance.
+ * 
+ * Return value: The new #GimpModule object.
+ **/
 GimpModule *
 gimp_module_new (const gchar *filename,
                  gboolean     load_inhibit,
@@ -265,6 +275,16 @@ gimp_module_new (const gchar *filename,
   return module;
 }
 
+/**
+ * gimp_module_query_module:
+ * @module: A #GimpModule.
+ * 
+ * Queries the module without actually registering any of the types it
+ * may implement. After successful query, the @info field of the
+ * #GimpModule struct will be available for further inspection.
+ * 
+ * Return value: #TRUE on success.
+ **/
 gboolean
 gimp_module_query_module (GimpModule *module)
 {
@@ -333,6 +353,13 @@ gimp_module_query_module (GimpModule *module)
   return TRUE;
 }
 
+/**
+ * gimp_module_modified:
+ * @module: A #GimpModule.
+ * 
+ * Emits the "modified" signal. Call it whenever you have modified the module
+ * manually (which you shouldn't do).
+ **/
 void
 gimp_module_modified (GimpModule *module)
 {
@@ -341,6 +368,13 @@ gimp_module_modified (GimpModule *module)
   g_signal_emit (G_OBJECT (module), module_signals[MODIFIED], 0);
 }
 
+/**
+ * gimp_module_set_load_inhibit:
+ * @module:       A #GimpModule.
+ * @load_inhibit: Pass #TRUE to exclude this module from auto-loading.
+ * 
+ * Sets the @load_inhibit property if the module. Emits "modified".
+ **/
 void
 gimp_module_set_load_inhibit (GimpModule *module,
                               gboolean    load_inhibit)
@@ -358,6 +392,15 @@ gimp_module_set_load_inhibit (GimpModule *module,
 
 /*  private functions  */
 
+/**
+ * gimp_module_state_name:
+ * @state: A #GimpModuleState.
+ * 
+ * Returns the translated textual representation of a #GimpModuleState.
+ * The returned string must not be freed.
+ * 
+ * Return value: The @state's name.
+ **/
 const gchar *
 gimp_module_state_name (GimpModuleState state)
 {
@@ -420,6 +463,19 @@ gimp_module_set_last_error (GimpModule  *module,
 
 /*  GimpModuleInfo functions  */
 
+/**
+ * gimp_module_info_new:
+ * @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.
+ * 
+ * Creates a newly allocated #GimpModuleInfo struct.
+ * 
+ * Return value: The new #GimpModuleInfo struct.
+ **/
 GimpModuleInfo *
 gimp_module_info_new (guint32      abi_version,
                       const gchar *purpose,
@@ -442,6 +498,14 @@ gimp_module_info_new (guint32      abi_version,
   return info;
 }
 
+/**
+ * gimp_module_info_copy:
+ * @info: The #GimpModuleInfo struct to copy.
+ * 
+ * Copies a #GimpModuleInfo struct.
+ * 
+ * Return value: The new copy.
+ **/
 GimpModuleInfo *
 gimp_module_info_copy (const GimpModuleInfo *info)
 {
@@ -455,6 +519,12 @@ gimp_module_info_copy (const GimpModuleInfo *info)
                                info->date);
 }
 
+/**
+ * gimp_module_info_free:
+ * @info: The #GimpModuleInfo struct to free
+ * 
+ * Frees the passed #GimpModuleInfo.
+ **/
 void
 gimp_module_info_free (GimpModuleInfo *info)
 {

libgimpmodule/gimpmodule.h

@@ -85,6 +85,7 @@ struct _GimpModule
 {
   GTypeModule      parent_instance;
 
+  /*< public >*/
   gchar           *filename;     /* path to the module                       */
   gboolean         verbose;      /* verbose error reporting                  */
   GimpModuleState  state;        /* what's happened to the module            */
@@ -92,10 +93,14 @@ struct _GimpModule
   gboolean         load_inhibit; /* user requests not to load at boot time   */
 
   /* stuff from now on may be NULL depending on the state the module is in   */
+  /*< private >*/
   GModule         *module;       /* handle on the module                     */
+
+  /*< public >*/
   GimpModuleInfo  *info;         /* returned values from module_query        */
   gchar           *last_module_error;
 
+  /*< private >*/
   GimpModuleQueryFunc     query_module;
   GimpModuleRegisterFunc  register_module;
 };

libgimpmodule/gimpmoduledb.c

@@ -186,6 +186,15 @@ gimp_module_db_finalize (GObject *object)
   G_OBJECT_CLASS (parent_class)->finalize (object);
 }
 
+/**
+ * gimp_module_db_new:
+ * @verbose: Pass #TRUE to enable debugging output.
+ * 
+ * Creates a new #GimpModuleDB instance. The @verbose parameter will be
+ * passed to the created #GimpModule instances using gimp_module_new().
+ * 
+ * Return value: The new #GimpModuleDB instance.
+ **/
 GimpModuleDB *
 gimp_module_db_new (gboolean verbose)
 {
@@ -234,6 +243,15 @@ is_in_inhibit_list (const gchar *filename,
   return FALSE;
 }
 
+/**
+ * gimp_module_db_set_load_inhibit:
+ * @db:           A #GimpModuleDB.
+ * @load_inhibit: A #G_SEARCHPATH_SEPARATOR delimited list of module
+ *                filenames to exclude from auto-loading.
+ * 
+ * Sets the @load_inhibit flag for all #GimpModule's which are kept
+ * by @db (using gimp_module_set_load_inhibit()).
+ **/
 void
 gimp_module_db_set_load_inhibit (GimpModuleDB *db,
                                  const gchar  *load_inhibit)
@@ -258,6 +276,15 @@ gimp_module_db_set_load_inhibit (GimpModuleDB *db,
     }
 }
 
+/**
+ * gimp_module_db_get_load_inhibit:
+ * @db: A #GimpModuleDB.
+ * 
+ * Return the #G_SEARCHPATH_SEPARATOR selimited list of module filenames
+ * which are excluded from auto-loading.
+ * 
+ * Return value: the @db's @load_inhibit string.
+ **/
 const gchar *
 gimp_module_db_get_load_inhibit (GimpModuleDB *db)
 {
@@ -266,6 +293,16 @@ gimp_module_db_get_load_inhibit (GimpModuleDB *db)
   return db->load_inhibit;
 }
 
+/**
+ * gimp_module_db_load:
+ * @db:          A #GimpModuleDB.
+ * @module_path: A #G_SEARCHPATH_SEPARATOR delimited list of directories
+ *               to load modules from.
+ * 
+ * Scans the directories contained in @module_path using
+ * gimp_datafiles_read_directories() and creates a #GimpModule
+ * instance for every loadable module contained in the directories.
+ **/
 void
 gimp_module_db_load (GimpModuleDB *db,
                      const gchar  *module_path)
@@ -284,6 +321,19 @@ gimp_module_db_load (GimpModuleDB *db,
 #endif
 }
 
+/**
+ * gimp_module_db_refresh:
+ * @db:          A #GimpModuleDB.
+ * @module_path: A #G_SEARCHPATH_SEPARATOR delimited list of directories
+ *               to load modules from.
+ * 
+ * Does the same as gimp_module_db_load(), plus removes all #GimpModule
+ * instances whose modules have been deleted from disk.
+ *
+ * Note that the #GimpModule's will just be removed from the internal
+ * list and not freed as this is not possible with #GTypeModule
+ * instances which actually implement types.
+ **/
 void
 gimp_module_db_refresh (GimpModuleDB *db,
                         const gchar  *module_path)
@@ -309,53 +359,6 @@ gimp_module_db_refresh (GimpModuleDB *db,
                                    db);
 }
 
-#if 0
-static void
-add_to_inhibit_string (gpointer data, 
-		       gpointer user_data)
-{
-  GimpModule *module = data;
-  GString    *str    = user_data;
-
-  if (module->load_inhibit)
-    {
-      str = g_string_append_c (str, G_SEARCHPATH_SEPARATOR);
-      str = g_string_append (str, module->filename);
-    }
-}
-
-static gboolean
-gimp_modules_write_modulerc (Gimp *gimp)
-{
-  GString  *str;
-  gchar    *p;
-  gchar    *filename;
-  FILE     *fp;
-  gboolean  saved = FALSE;
-
-  str = g_string_new (NULL);
-  gimp_container_foreach (gimp->modules, add_to_inhibit_string, str);
-  if (str->len > 0)
-    p = str->str + 1;
-  else
-    p = "";
-
-  filename = gimp_personal_rc_file ("modulerc");
-  fp = fopen (filename, "wt");
-  g_free (filename);
-  if (fp)
-    {
-      fprintf (fp, "(module-load-inhibit \"%s\")\n", p);
-      fclose (fp);
-      saved = TRUE;
-    }
-
-  g_string_free (str, TRUE);
-
-  return saved;
-}
-#endif
-
 /* name must be of the form lib*.so (Unix) or *.dll (Win32) */
 static gboolean
 valid_module_name (const gchar *filename)

libgimpmodule/gimpmoduledb.h

@@ -39,6 +39,7 @@ struct _GimpModuleDB
 {
   GObject   parent_instance;
 
+  /*< private >*/
   GList    *modules;
 
   gchar    *load_inhibit;