Document all functions inside c-source

- Taken from old sgml template
- Less compilation warnings now

16 files changed, 234 insertions, 7 deletions

diff --git a/thunarx/thunarx-file-info.c b/thunarx/thunarx-file-info.c
index 4d103a78..763382ef 100644
--- a/thunarx/thunarx-file-info.c
+++ b/thunarx/thunarx-file-info.c
@@ -40,6 +40,15 @@ enum
 
 static guint file_info_signals[LAST_SIGNAL];
 
+/**
+ * SECTION: thunarx-file-info
+ * @short_description: Abstraction of a file handled within the file manager
+ * @title: ThunarxFileInfo
+ * @include: thunarx/thunarx.h
+ *
+ * The <interface>ThunarxFileInfo</interface> interface provides extensions with
+ * a way to access information about a file handled within the file manager.
+ */
 
 
 GType
diff --git a/thunarx/thunarx-file-info.h b/thunarx/thunarx-file-info.h
index 76bbaa11..b0bb09ab 100644
--- a/thunarx/thunarx-file-info.h
+++ b/thunarx/thunarx-file-info.h
@@ -66,6 +66,25 @@ typedef struct _ThunarxFileInfo      ThunarxFileInfo;
 #define THUNARX_IS_FILE_INFO(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), THUNARX_TYPE_FILE_INFO))
 #define THUNARX_FILE_INFO_GET_IFACE(obj)  (G_TYPE_INSTANCE_GET_INTERFACE ((obj), THUNARX_TYPE_FILE_INFO, ThunarxFileInfoIface))
 
+/**
+ * ThunarxFileInfoIface:
+ * @get_name: See thunarx_file_info_get_name().
+ * @get_uri: See thunarx_file_info_get_uri().
+ * @get_parent_uri: See thunarx_file_info_get_parent_uri().
+ * @get_uri_scheme: See thunarx_file_info_get_uri_scheme().
+ * @get_mime_type: See thunarx_file_info_get_mime_type().
+ * @has_mime_type: See thunarx_file_info_has_mime_type().
+ * @is_directory: See thunarx_file_info_is_directory().
+ * @get_file_info: See thunarx_file_info_get_file_info().
+ * @get_filesystem_info: See thunarx_filesystem_info_get_filesystem_info().
+ * @get_location: See thunarx_location_get_location().
+ * @changed: See thunarx_file_info_changed().
+ * @renamed: See thunarx_file_info_renamed().
+ *
+ * Interface with virtual methods implemented by the file manager and accessible
+ * from the extensions.
+ */
+
 struct _ThunarxFileInfoIface
 {
   /*< private >*/
diff --git a/thunarx/thunarx-menu-provider.c b/thunarx/thunarx-menu-provider.c
index f7348df0..9fd77f07 100644
--- a/thunarx/thunarx-menu-provider.c
+++ b/thunarx/thunarx-menu-provider.c
@@ -26,6 +26,32 @@
 #include <thunarx/thunarx-private.h>
 
 
+/**
+ * SECTION: thunarx-menu-provider
+ * @short_description: The interface to extensions that provide additional menu items
+ * @title: ThunarxMenuProvider
+ * @include: thunarx/thunarx.h
+ *
+ * The <interface>ThunarxMenuProvider</interface> interface is implemented by
+ * extensions which provide additional menu items that should be displayed in
+ * the file or folder context menus for certain types of files.
+ *
+ * Extensions that implement this interface should do its best to respond as
+ * fast as possible to method invokations by the file manager. That said, when
+ * the file manager calls the thunarx_menu_provider_get_file_actions() or the
+ * thunarx_menu_provider_get_folder_actions() method, the implementation in the
+ * extension should use only the thunarx_file_info_has_mime_type() and
+ * thunarx_file_info_is_directory() methods to determine the actions that should
+ * be added to the file manager's context menu. Don't perform any complicated I/O
+ * to determine the action list, as that would block the whole file manager process.
+ *
+ * The <link linkend="GtkAction">GtkAction</link>s returned from the
+ * thunarx_menu_provider_get_file_actions() and thunarx_menu_provider_get_folder_actions()
+ * methods must be namespaced with the module to avoid collision with internal file manager
+ * actions and actions provided by other extensions. For example, the menu action provided
+ * by the <systemitem class="library">ThunarOpenTerminal</systemitem> extension should be
+ * called <literal>ThunarOpenTerminal::open-terminal</literal>.
+ */
 
 GType
 thunarx_menu_provider_get_type (void)
diff --git a/thunarx/thunarx-menu-provider.h b/thunarx/thunarx-menu-provider.h
index 2b8fdb9d..1adabcc9 100644
--- a/thunarx/thunarx-menu-provider.h
+++ b/thunarx/thunarx-menu-provider.h
@@ -39,6 +39,18 @@ typedef struct _ThunarxMenuProvider      ThunarxMenuProvider;
 #define THUNARX_IS_MENU_PROVIDER(obj)        (G_TYPE_CHECK_INSTANCE_TYPE ((obj), THUNARX_TYPE_MENU_PROVIDER))
 #define THUNARX_MENU_PROVIDER_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), THUNARX_TYPE_MENU_PROVIDER, ThunarxMenuProviderIface))
 
+/**
+ * ThunarxMenuProviderIface:
+ * @get_file_actions: See thunarx_menu_provider_get_file_actions().
+ * @get_folder_actions: See thunarx_menu_provider_get_folder_actions().
+ * @get_dnd_actions: See thunarx_menu_provider_get_dnd_actions().
+ *
+ * Interface with virtual methods implemented by extensions that provide
+ * additional menu items for the file manager's context menus.
+ * Providers don't need to implement all of the virtual methods listed in
+ * the interface.
+ */
+
 struct _ThunarxMenuProviderIface
 {
   /*< private >*/
diff --git a/thunarx/thunarx-preferences-provider.c b/thunarx/thunarx-preferences-provider.c
index fc6140b6..e4908f5c 100644
--- a/thunarx/thunarx-preferences-provider.c
+++ b/thunarx/thunarx-preferences-provider.c
@@ -25,7 +25,29 @@
 #include <thunarx/thunarx-preferences-provider.h>
 #include <thunarx/thunarx-private.h>
 
-
+/**
+ * SECTION: thunarx-preferences-provider
+ * @short_description: The interface to extensions that provide preferences
+ * @title: ThunarxPreferencesProvider
+ * @include: thunarx/thunarx.h
+ *
+ * The ThunarxPreferencesProvider interface is implemented by extensions that
+ * want to register additional actions in the preferences menu of the file
+ * manager. In general this should only be done by extensions that are closely
+ * tied to the file manager (for example, the <literal>thunar-uca</literal> is
+ * such an extension, while an extension that just adds <guimenuitem>Compress
+ * file</guimenuitem> and <guimenuitem>Uncompress file</guimenuitem> to the
+ * context menu of compressed files should not add their own preferences to
+ * the file manager menu, because it should use desktop-wide settings for
+ * archive managers instead).
+ *
+ * The <link linkend="GtkAction"><type>GtkAction</type></link>s returned from the
+ * thunarx_preferences_provider_get_actions() method must be namespaced with the
+ * model to avoid collision with internal file manager actions and actions provided
+ * by other extensions. For example, the preferences action provided by the
+ * <literal>thunar-uca</literal> extension is called
+ * <literal>ThunarUca::manage-actions</literal>.
+ */
 
 GType
 thunarx_preferences_provider_get_type (void)
diff --git a/thunarx/thunarx-preferences-provider.h b/thunarx/thunarx-preferences-provider.h
index 505c673c..856c5a18 100644
--- a/thunarx/thunarx-preferences-provider.h
+++ b/thunarx/thunarx-preferences-provider.h
@@ -37,6 +37,16 @@ typedef struct _ThunarxPreferencesProvider      ThunarxPreferencesProvider;
 #define THUNARX_IS_PREFERENCES_PROVIDER(obj)        (G_TYPE_CHECK_INSTANCE_TYPE ((obj), THUNARX_TYPE_PREFERENCES_PROVIDER))
 #define THUNARX_PREFERENCES_PROVIDER_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), THUNARX_TYPE_PREFERENCES_PROVIDER, ThunarxPreferencesProviderIface))
 
+/**
+ * ThunarxPreferencesProviderIface:
+ * @get_actions: See thunarx_preferences_provider_get_actions().
+ *
+ * Interface with virtual methods implementation by extensions that
+ * want to install preferences actions in the file managers menu.
+ * Providers don't need to implement all of the virtual methods listed
+ * in the interface.
+ */
+
 struct _ThunarxPreferencesProviderIface
 {
   /*< private >*/
diff --git a/thunarx/thunarx-property-page-provider.c b/thunarx/thunarx-property-page-provider.c
index 9e666470..36ca5457 100644
--- a/thunarx/thunarx-property-page-provider.c
+++ b/thunarx/thunarx-property-page-provider.c
@@ -25,7 +25,18 @@
 #include <thunarx/thunarx-private.h>
 #include <thunarx/thunarx-property-page-provider.h>
 
-
+/**
+ * SECTION: thunarx-property-page-provider
+ * @short_description: The interface to extensions that provide additional property pages
+ * @title: ThunarxPropertyPageProvider
+ * @include: thunarx/thunarx.h
+ *
+ * To add a property page to the file properties dialog, extensions must implement the
+ * <type>ThunarxPropertyPageProvider</type> interface. This interface has only one virtual
+ * method, <function>get_pages</function>, that is passed a list of <link
+ * linkend="ThunarxFileInfo"><type>ThunarxFileInfo</type></link> objects and returns a list
+ * of <link linkend="ThunarxPropertyPage"><type>ThunarxPropertyPage</type></link> objects.
+ */
 
 GType
 thunarx_property_page_provider_get_type (void)
diff --git a/thunarx/thunarx-property-page-provider.h b/thunarx/thunarx-property-page-provider.h
index 69ef814a..bb6f90d9 100644
--- a/thunarx/thunarx-property-page-provider.h
+++ b/thunarx/thunarx-property-page-provider.h
@@ -37,6 +37,13 @@ typedef struct _ThunarxPropertyPageProvider      ThunarxPropertyPageProvider;
 #define THUNARX_IS_PROPERTY_PAGE_PROVIDER(obj)        (G_TYPE_CHECK_INSTANCE_TYPE ((obj), THUNARX_TYPE_PROPERTY_PAGE_PROVIDER))
 #define THUNARX_PROPERTY_PAGE_PROVIDER_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), THUNARX_TYPE_PROPERTY_PAGE_PROVIDER, ThunarxPropertyPageProviderIface))
 
+/**
+ * ThunarxPropertyPageProviderIface:
+ * @get_pages: see thunarx_property_page_provider_get_pages().
+ *
+ * Interface with virtual methods implemented by extensions that provide
+ * additional pages for the file properties dialog.
+ */
 struct _ThunarxPropertyPageProviderIface
 {
   /*< private >*/
diff --git a/thunarx/thunarx-property-page.c b/thunarx/thunarx-property-page.c
index aec8e6a4..a62bddff 100644
--- a/thunarx/thunarx-property-page.c
+++ b/thunarx/thunarx-property-page.c
@@ -31,7 +31,30 @@
 
 #define THUNARX_PROPERTY_PAGE_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), THUNARX_TYPE_PROPERTY_PAGE, ThunarxPropertyPagePrivate))
 
-
+/**
+ * SECTION: thunarx-property-page
+ * @short_description: The base class for pages added to the properties dialog
+ * @title: ThunarxPropertyPage
+ * @include: thunarx/thunarx.h
+ *
+ * The class for pages that can be added to Thunar's file properties dialog
+ * by extensions implementing the #ThunarxPropertyPageProvider interface. The
+ * pages returned by extensions from thunarx_property_page_provider_get_pages()
+ * method are instances of this class or a derived class. Note that extensions
+ * do not need to subclass #ThunarxPropertyPage, but may also instantiate it
+ * directly and add widgets to it, but I strongly suggest to create a subclass
+ * as it usually leads to better modularization and thereby better maintainability
+ * in the code.
+ *
+ * To pick up the #TagPage example from the thunarx_property_page_provider_get_pages()
+ * description again, you'd create a new class #TagPage, that inherits #ThunarxPropertyPage
+ * (using the #THUNARX_DEFINE_TYPE macro), which provides several user interface elements
+ * in the property, and defines atleast one property named <literal>"file"</literal>, which
+ * is the #ThunarxFileInfo whose tags are displayed in the property page. For example, the
+ * <filename>tag-page.h</filename> header file would look like this (this is really just
+ * an example of the suggested way to implement property pages, you may of course choose
+ * a different way)
+ */
 
 /* Property identifiers */
 enum
diff --git a/thunarx/thunarx-provider-factory.c b/thunarx/thunarx-provider-factory.c
index 31b88354..6707b6d9 100644
--- a/thunarx/thunarx-provider-factory.c
+++ b/thunarx/thunarx-provider-factory.c
@@ -43,7 +43,16 @@ static GList   *thunarx_provider_factory_load_modules   (ThunarxProviderFactory
 static gboolean thunarx_provider_factory_timer          (gpointer                     user_data);
 static void     thunarx_provider_factory_timer_destroy  (gpointer                     user_data);
 
-
+/**
+ * SECTION: thunarx-provider-factory
+ * @short_description: The provider factory support for applications
+ * @title: ThunarxProviderFactory
+ * @include: thunarx/thunarx.h
+ *
+ * The #ThunarxProviderFactory class allows applications to use Thunar plugins. It handles
+ * the loading of the installed extensions and instantiates providers for the application.
+ * For example, Thunar uses this class to access the installed extensions.
+ */
 
 typedef struct
 {
diff --git a/thunarx/thunarx-provider-plugin.c b/thunarx/thunarx-provider-plugin.c
index ac3309b4..d5e74474 100644
--- a/thunarx/thunarx-provider-plugin.c
+++ b/thunarx/thunarx-provider-plugin.c
@@ -31,7 +31,16 @@
 
 static void thunarx_provider_plugin_class_init (gpointer klass);
 
-
+/**
+ * SECTION: thunarx-provider-plugin
+ * @short_description: The interface to the plugin type registration
+ * @title: ThunarxProviderPlugin
+ * @include: thunarx/thunarx.h
+ *
+ * #ThunarxProviderPlugin is the interface to the file manager's type plugin loader implementation. It
+ * provides methods to extensions - also called <emphasis>provider plugins</emphasis> - to register dynamic
+ * types and control certain aspects of the plugin (see thunarx_provider_plugin_set_resident()).
+ */
 
 GType
 thunarx_provider_plugin_get_type (void)
diff --git a/thunarx/thunarx-provider-plugin.h b/thunarx/thunarx-provider-plugin.h
index 6fd19aa8..02c06269 100644
--- a/thunarx/thunarx-provider-plugin.h
+++ b/thunarx/thunarx-provider-plugin.h
@@ -35,6 +35,19 @@ typedef struct _ThunarxProviderPlugin      ThunarxProviderPlugin;
 #define THUNARX_IS_PROVIDER_PLUGIN(obj)        (G_TYPE_CHECK_INSTANCE_TYPE ((obj), THUNARX_TYPE_PROVIDER_PLUGIN))
 #define THUNARX_PROVIDER_PLUGIN_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), THUNARX_TYPE_PROVIDER_PLUGIN, ThunarxProviderPluginIface))
 
+/**
+ * ThunarxProviderPluginIface:
+ * @get_resident: see thunarx_provider_plugin_get_resident().
+ * @set_resident: see thunarx_provider_plugin_set_resident().
+ * @register_type: see thunarx_provider_plugin_register_type().
+ * @add_interface: see thunarx_provider_plugin_add_interface().
+ * @register_enum: see thunarx_provider_plugin_register_enum().
+ * @register_flags: see thunarx_provider_plugin_register_flags().
+ *
+ * Interface with virtual methods implemented by the file manager and
+ * accessible from the extensions.
+ */
+
 struct _ThunarxProviderPluginIface
 {
   /*< private >*/
diff --git a/thunarx/thunarx-renamer-provider.c b/thunarx/thunarx-renamer-provider.c
index ae2bc17a..21c8487f 100644
--- a/thunarx/thunarx-renamer-provider.c
+++ b/thunarx/thunarx-renamer-provider.c
@@ -25,7 +25,16 @@
 #include <thunarx/thunarx-renamer-provider.h>
 #include <thunarx/thunarx-private.h>
 
-
+/**
+ * SECTION: thunarx-renamer-provider
+ * @short_description: The interface to extensions that provide additional bulk renamers
+ * @title: ThunarxRenamerProvider
+ * @include: thunarx/thunarx.h
+ *
+ * The <interface>ThunarxRenamerProvider</interface> interface is implemented by
+ * extensions which provide additional bulk renamers that should be used by the
+ * bulk rename dialog in Thunar.
+ */
 
 GType
 thunarx_renamer_provider_get_type (void)
diff --git a/thunarx/thunarx-renamer-provider.h b/thunarx/thunarx-renamer-provider.h
index 2ace381e..5dfb4d96 100644
--- a/thunarx/thunarx-renamer-provider.h
+++ b/thunarx/thunarx-renamer-provider.h
@@ -37,6 +37,14 @@ typedef struct _ThunarxRenamerProvider      ThunarxRenamerProvider;
 #define THUNARX_IS_RENAMER_PROVIDER(obj)        (G_TYPE_CHECK_INSTANCE_TYPE ((obj), THUNARX_TYPE_RENAMER_PROVIDER))
 #define THUNARX_RENAMER_PROVIDER_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), THUNARX_TYPE_RENAMER_PROVIDER, ThunarxRenamerProviderIface))
 
+/**
+ * ThunarxRenamerProviderIface:
+ * @get_renamers: see thunarx_renamer_provider_get_renamers().
+ *
+ * Interface with virtual methods implemented by extensions that provide
+ * additional bulk renamers for the integrated bulk renamer in Thunar.
+ */
+
 struct _ThunarxRenamerProviderIface
 {
   /*< private >*/
diff --git a/thunarx/thunarx-renamer.c b/thunarx/thunarx-renamer.c
index 1d8c4426..cec3a697 100644
--- a/thunarx/thunarx-renamer.c
+++ b/thunarx/thunarx-renamer.c
@@ -49,6 +49,32 @@ enum
 };
 
 
+/**
+ * SECTION: thunarx-renamer
+ * @short_description: The abstract base class for bulk renamers
+ * @title: ThunarxRenamer
+ * @include: thunarx/thunarx.h
+ * @image: bulk-rename.png
+ *
+ * The abstract base class <type>ThunarxRenamer</type> is implemented by
+ * extensions which provide additional bulk renamers that should be used in
+ * the bulk rename dialog.
+ *
+ * Derived classes must override the thunarx_renamer_process() method, which
+ * is called by the bulk rename dialog for every file to generate a new name. For
+ * example, the <type>ThunarSbrReplaceRenamer</type> class included in the
+ * <literal>thunar-sbr</literal> plugin (which is part of the Thunar distribution)
+ * provides a bulk renamer, named <emphasis>Search &amp; Replace</emphasis>,
+ * which allows the user to rename multiple files by searching for a pattern in
+ * each file name and, if the pattern is found, replacing it with the specified
+ * replacement text.
+ *
+ * The active <type>ThunarxRenamer</type>s user interface is displayed in a frame
+ * below the file list, as shown in the screenshot above. Derived classes should try
+ * to limit the number of widgets displayed in the main user interface. For example,
+ * if you have more than six settings, you should consider adding an <guibutton>Advanced</guibutton>,
+ * button which opens a dialog with the additional settings.
+ */
 
 static void     thunarx_renamer_finalize          (GObject                *object);
 static GObject *thunarx_renamer_constructor       (GType                   type,
diff --git a/thunarx/thunarx-renamer.h b/thunarx/thunarx-renamer.h
index 65829b3d..8143aa80 100644
--- a/thunarx/thunarx-renamer.h
+++ b/thunarx/thunarx-renamer.h
@@ -42,6 +42,20 @@ typedef struct _ThunarxRenamer        ThunarxRenamer;
 #define THUNARX_IS_RENAMER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), THUNARX_TYPE_RENAMER))
 #define THUNARX_RENAMER_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), THUNARX_TYPE_RENAMER, ThunarxRenamerClass))
 
+/**
+ * ThunarxRenamerClass:
+ * @process: 	see thunarx_renamer_process().
+ * @load:    	see thunarx_renamer_load().
+ * @save:    	see thunarx_renamer_save().
+ * @get_actions: 	see thunarx_renamer_get_actions().
+ * @changed: 	see thunarx_renamer_changed().
+ *
+ * Abstract base class with virtual methods implemented by extensions
+ * that provide additional bulk renamers for the integrated bulk
+ * rename module in Thunar.
+ *
+ */
+
 struct _ThunarxRenamerClass
 {
   /*< private >*/
@@ -103,7 +117,7 @@ void         thunarx_renamer_set_name     (ThunarxRenamer   *renamer,
 gchar       *thunarx_renamer_process      (ThunarxRenamer   *renamer,
                                            ThunarxFileInfo  *file,
                                            const gchar      *text,
-                                           guint             index) G_GNUC_MALLOC;
+                                           guint             idx) G_GNUC_MALLOC;
 
 void         thunarx_renamer_load         (ThunarxRenamer   *renamer,
                                            GHashTable       *settings);