[Xfce4-commits] [xfce/thunar] 02/02: Document all functions inside c-source
noreply at xfce.org
noreply at xfce.org
Mon Sep 18 02:25:10 CEST 2017
This is an automated email from the git hooks/post-receive script.
a n d r e p u s h e d a c o m m i t t o b r a n c h m a s t e r
in repository xfce/thunar.
commit babf85c175e090f59f26b7af7579811687303129
Author: Romain B <skunnyk at alteroot.org>
Date: Sun Sep 17 17:24:32 2017 +0200
Document all functions inside c-source
- Taken from old sgml template
- Less compilation warnings now
---
thunarx/thunarx-file-info.c | 9 +++++++++
thunarx/thunarx-file-info.h | 19 +++++++++++++++++++
thunarx/thunarx-menu-provider.c | 26 ++++++++++++++++++++++++++
thunarx/thunarx-menu-provider.h | 12 ++++++++++++
thunarx/thunarx-preferences-provider.c | 24 +++++++++++++++++++++++-
thunarx/thunarx-preferences-provider.h | 10 ++++++++++
thunarx/thunarx-property-page-provider.c | 13 ++++++++++++-
thunarx/thunarx-property-page-provider.h | 7 +++++++
thunarx/thunarx-property-page.c | 25 ++++++++++++++++++++++++-
thunarx/thunarx-provider-factory.c | 11 ++++++++++-
thunarx/thunarx-provider-plugin.c | 11 ++++++++++-
thunarx/thunarx-provider-plugin.h | 13 +++++++++++++
thunarx/thunarx-renamer-provider.c | 11 ++++++++++-
thunarx/thunarx-renamer-provider.h | 8 ++++++++
thunarx/thunarx-renamer.c | 26 ++++++++++++++++++++++++++
thunarx/thunarx-renamer.h | 16 +++++++++++++++-
16 files changed, 234 insertions(+), 7 deletions(-)
diff --git a/thunarx/thunarx-file-info.c b/thunarx/thunarx-file-info.c
index 4d103a7..763382e 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 76bbaa1..b0bb09a 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 f7348df..9fd77f0 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 2b8fdb9..1adabcc 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 fc6140b..e4908f5 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 505c673..856c5a1 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 9e66647..36ca545 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 69ef814..bb6f90d 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 aec8e6a..a62bddf 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 31b8835..6707b6d 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 ac3309b..d5e7447 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 6fd19aa..02c0626 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 ae2bc17..21c8487 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 2ace381..5dfb4d9 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 1d8c442..cec3a69 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 & 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 65829b3..8143aa8 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);
--
To stop receiving notification emails like this one, please contact
the administrator of this repository.
More information about the Xfce4-commits
mailing list