[Xfce4-commits] [xfce/libxfce4util] 01/02: Improve gobject-introspection annotations
noreply at xfce.org
noreply at xfce.org
Sat Jun 24 19:34:11 CEST 2017
This is an automated email from the git hooks/post-receive script.
e r i c 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/libxfce4util.
commit a634b5518d20d45a187ca69adb204c57e8bf9e9f
Author: Eric Koegel <eric.koegel at gmail.com>
Date: Sat Jun 24 11:21:58 2017 +0300
Improve gobject-introspection annotations
---
libxfce4util/Makefile.am | 2 +-
libxfce4util/xfce-fileutils.c | 6 +++---
libxfce4util/xfce-kiosk.c | 13 ++++++++-----
libxfce4util/xfce-miscutils.c | 4 ++--
libxfce4util/xfce-posix-signal-handler.c | 28 ++++++++++++++--------------
libxfce4util/xfce-rc.c | 25 +++++++++++++++++--------
libxfce4util/xfce-resource.c | 19 +++++++++----------
7 files changed, 54 insertions(+), 43 deletions(-)
diff --git a/libxfce4util/Makefile.am b/libxfce4util/Makefile.am
index f3cc4dd..a0cf544 100644
--- a/libxfce4util/Makefile.am
+++ b/libxfce4util/Makefile.am
@@ -96,7 +96,7 @@ INTROSPECTION_COMPILER_ARGS = \
--includedir=.
if HAVE_INTROSPECTION
-introspection_sources = $(filter-out %private.h %.c, $(libxfce4util_la_SOURCES))
+introspection_sources = $(filter-out %private.h, $(libxfce4util_la_SOURCES))
libxfce4util-1.0.gir: libxfce4util.la Makefile
libxfce4util_1_0_gir_INCLUDES = GObject-2.0 GLib-2.0
diff --git a/libxfce4util/xfce-fileutils.c b/libxfce4util/xfce-fileutils.c
index 51d5cb6..dd26849 100644
--- a/libxfce4util/xfce-fileutils.c
+++ b/libxfce4util/xfce-fileutils.c
@@ -45,7 +45,7 @@
/**
* xfce_mkdirhier:
* @whole_path : path to the directory to create.
- * @omode : file permissions to use for the newly created directories.
+ * @mode : file permissions to use for the newly created directories.
* @error : location where to store GError object to, error are returned
* in the %G_FILE_ERROR domain.
*
@@ -62,7 +62,7 @@
**/
gboolean
xfce_mkdirhier (const gchar *whole_path,
- gulong omode,
+ gulong mode,
GError **error)
{
/* Stolen from FreeBSD's mkdir(1) with modifications to make it
@@ -118,7 +118,7 @@ xfce_mkdirhier (const gchar *whole_path,
if (last)
umask(oumask);
- if (mkdir (path, last ? omode : S_IRWXU | S_IRWXG | S_IRWXO) < 0)
+ if (mkdir (path, last ? mode : S_IRWXU | S_IRWXG | S_IRWXO) < 0)
{
sverrno = errno;
diff --git a/libxfce4util/xfce-kiosk.c b/libxfce4util/xfce-kiosk.c
index 67d48eb..24feb4d 100644
--- a/libxfce4util/xfce-kiosk.c
+++ b/libxfce4util/xfce-kiosk.c
@@ -93,10 +93,12 @@ xfce_kiosk_class_init (XfceKioskClass *klass)
}
/**
- * xfce_kiosk_new:
- * @module:
+ * xfce_kiosk_new: (constructor)
+ * @module: The Xfce project to query about
*
- * FIXME
+ * Creates and returns a new instance of #XfceKiosk.
+ *
+ * Return value: (transfer full): a new instance of #XfceKiosk.
*
* Since: 4.2
**/
@@ -107,7 +109,7 @@ xfce_kiosk_new (const gchar *module)
gchar path[1024];
g_return_val_if_fail (module != NULL, NULL);
- g_return_val_if_fail (strcmp (module, "General") != 0, NULL);
+ g_return_val_if_fail (g_strcmp0 (module, "General") != 0, NULL);
g_snprintf (path, 1024, "%s/%s.kioskrc", KIOSKDIR, module);
@@ -206,6 +208,7 @@ xfce_kiosk_finalize (GObject *object)
* @kiosk: A #XfceKiosk.
*
* Frees the @kiosk object.
+ * In 4.13 and above, this is equivalent to calling g_clear_object.
*
* Since: 4.2
*/
@@ -214,7 +217,7 @@ xfce_kiosk_free (XfceKiosk *kiosk)
{
/* finalize takes care of things in case the consumer calls unref
* themselves instead of this function */
- g_object_unref (kiosk);
+ g_clear_object (&kiosk);
}
diff --git a/libxfce4util/xfce-miscutils.c b/libxfce4util/xfce-miscutils.c
index bf4c118..27b4af8 100644
--- a/libxfce4util/xfce-miscutils.c
+++ b/libxfce4util/xfce-miscutils.c
@@ -190,7 +190,7 @@ xfce_get_homedir (void)
* @buffer : pointer to a user provided destination buffer.
* @length : size of @buffer in bytes.
* @format : printf style format string.
- * @Varargs : the arguments to substitute in the output.
+ * @... : the arguments to substitute in the output.
*
* Similar in functionality to #xfce_get_homefile, but uses a user
* defined @buffer instead of allocating a new buffer.
@@ -255,7 +255,7 @@ xfce_get_userdir (void)
* @buffer : user provided destination buffer.
* @length : size of @buffer in bytes.
* @format : printf style format string.
- * @Varargs : arguments to substitute in the output.
+ * @... : arguments to substitute in the output.
*
* Return value: pointer to @buffer.
**/
diff --git a/libxfce4util/xfce-posix-signal-handler.c b/libxfce4util/xfce-posix-signal-handler.c
index a31f800..425519e 100644
--- a/libxfce4util/xfce-posix-signal-handler.c
+++ b/libxfce4util/xfce-posix-signal-handler.c
@@ -112,7 +112,7 @@ xfce_posix_signal_handler(gint signal_id)
/**
* xfce_posix_signal_handler_init:
- * @error: Location of a #GError to store any possible errors.
+ * @error: (out) (allow-none) (transfer full): Location of a #GError to store any possible errors.
*
* Initializes the POSIX signal handler system. Must be called
* before setting any POSIX signal handlers.
@@ -178,10 +178,10 @@ xfce_posix_signal_handler_shutdown(void)
/**
* xfce_posix_signal_handler_set_handler:
- * @signal_id: A POSIX signal id number.
- * @handler: A callback function.
+ * @signal: A POSIX signal id number.
+ * @handler: (scope call): A callback function.
* @user_data: Arbitrary data that will be passed to @handler.
- * @error: Location of a #GError to store any possible errors.
+ * @error: (out) (allow-none) (transfer full): Location of a #GError to store any possible errors.
*
* Sets @handler to be called whenever @signal is caught by the
* application. The @user_data parameter will be passed as an argument
@@ -191,7 +191,7 @@ xfce_posix_signal_handler_shutdown(void)
* @error will be set.
**/
gboolean
-xfce_posix_signal_handler_set_handler(gint signal_id,
+xfce_posix_signal_handler_set_handler(gint signal,
XfcePosixSignalHandler handler,
gpointer user_data,
GError **error)
@@ -209,15 +209,15 @@ xfce_posix_signal_handler_set_handler(gint signal_id,
if(!handler) {
g_warning("NULL signal handler supplied; removing existing handler");
- xfce_posix_signal_handler_restore_handler(signal_id);
+ xfce_posix_signal_handler_restore_handler(signal);
return TRUE;
}
- if(g_hash_table_lookup(__handlers, GINT_TO_POINTER(signal_id)))
- xfce_posix_signal_handler_restore_handler(signal_id);
+ if(g_hash_table_lookup(__handlers, GINT_TO_POINTER(signal)))
+ xfce_posix_signal_handler_restore_handler(signal);
hdata = g_new0(XfcePosixSignalHandlerData, 1);
- hdata->signal_id = signal_id;
+ hdata->signal_id = signal;
hdata->handler = handler;
hdata->user_data = user_data;
@@ -225,7 +225,7 @@ xfce_posix_signal_handler_set_handler(gint signal_id,
sa.sa_handler = xfce_posix_signal_handler;
sa.sa_flags = SA_RESTART;
- if(sigaction(signal_id, &sa, &hdata->old_sa)) {
+ if(sigaction(signal, &sa, &hdata->old_sa)) {
if(error) {
g_set_error(error, G_FILE_ERROR, g_file_error_from_errno(errno),
_("sigaction() failed: %s\n"), strerror(errno));
@@ -234,24 +234,24 @@ xfce_posix_signal_handler_set_handler(gint signal_id,
return FALSE;
}
- g_hash_table_insert(__handlers, GINT_TO_POINTER(signal_id), hdata);
+ g_hash_table_insert(__handlers, GINT_TO_POINTER(signal), hdata);
return TRUE;
}
/**
* xfce_posix_signal_handler_restore_handler:
- * @signal_id: A POSIX signal id number.
+ * @signal: A POSIX signal id number.
*
* Restores the default handler for @signal.
**/
void
-xfce_posix_signal_handler_restore_handler(gint signal_id)
+xfce_posix_signal_handler_restore_handler(gint signal)
{
if(G_UNLIKELY(!__inited))
return;
- g_hash_table_remove(__handlers, GINT_TO_POINTER(signal_id));
+ g_hash_table_remove(__handlers, GINT_TO_POINTER(signal));
}
diff --git a/libxfce4util/xfce-rc.c b/libxfce4util/xfce-rc.c
index bda88e6..47685d0 100644
--- a/libxfce4util/xfce-rc.c
+++ b/libxfce4util/xfce-rc.c
@@ -90,7 +90,7 @@ _xfce_rc_init (XfceRc *rc)
* does not exists. In this case you'll start with a fresh config, which contains
* only the default group and no entries.
*
- * Return value: the newly created #XfceRc object, or %NULL on error.
+ * Return value: (transfer full): the newly created #XfceRc object, or %NULL on error.
*
* Since: 4.2
**/
@@ -121,11 +121,20 @@ xfce_rc_simple_open (const gchar *filename,
/**
* xfce_rc_config_open:
- * @type :
- * @resource :
- * @readonly :
+ * @type : The resource type being opened
+ * @resource : The resource name to open
+ * @readonly : whether to open @resource readonly.
*
- * Return value:
+ * If @readonly is %TRUE parsing is generally faster, because only untranslated
+ * entries and entries that match the current locale will be loaded. Also if
+ * you pass %TRUE for @readonly, #xfce_rc_config will fail if @resource
+ * does not reference a regular file.
+ *
+ * It is no error if @readonly is %FALSE and the file referenced by @resource
+ * does not exists. In this case you'll start with a fresh config, which contains
+ * only the default group and no entries.
+ *
+ * Return value: (transfer full): the newly created #XfceRc object, or %NULL on error.
*
* Since: 4.2
**/
@@ -294,7 +303,7 @@ xfce_rc_get_locale (const XfceRc *rc)
* returned with this functions. But it does not matter at all, since the
* default group is known to always exist.
*
- * Return value: a NULL-terminated string array will the names of all groups in
+ * Return value: (transfer full): a NULL-terminated string array will the names of all groups in
* @rc. Should be freed using g_strfreev() when no longer needed.
*
* Since: 4.2
@@ -322,7 +331,7 @@ xfce_rc_get_groups (const XfceRc *rc)
* "NULL group" should only be used for backward compatibility with old
* applications. You should not use it in newly written code.
*
- * Return value: a NULL-terminated string array with all entries in @group. Has to
+ * Return value: (transfer full): a NULL-terminated string array with all entries in @group. Has to
* be freed using g_strfreev() if no longer needed. If the specified
* @group does not exists, %NULL is returned. If the @group has no entries,
* an empty string array is returned.
@@ -636,7 +645,7 @@ xfce_rc_read_int_entry (const XfceRc *rc,
* Reads a list of strings in the entry specified by key in the current group.
* The returned list has to be freed using g_strfreev() when no longer needed.
*
- * Return value: the list or NULL if the entry does not exist.
+ * Return value: (transfer full): the list or NULL if the entry does not exist.
*
* Since: 4.2
**/
diff --git a/libxfce4util/xfce-resource.c b/libxfce4util/xfce-resource.c
index d39e6ad..c4663d3 100644
--- a/libxfce4util/xfce-resource.c
+++ b/libxfce4util/xfce-resource.c
@@ -409,7 +409,7 @@ _res_match_path (const gchar *path,
*
* The returned list must be freed using g_strfreev().
*
- * Return value: list of possible directories for @type.
+ * Return value: (transfer full): list of possible directories for @type.
*
* Since: 4.2
**/
@@ -460,7 +460,7 @@ xfce_resource_dirs (XfceResourceType type)
* The caller is responsible to free the returned string using g_free()
* when no longer needed.
*
- * Return value: the absolute path to the first file or directory in the
+ * Return value: (transfer full): the absolute path to the first file or directory in the
* search path, that matches @filename or %NULL if no such
* file or directory could be found.
*
@@ -513,7 +513,7 @@ xfce_resource_lookup (XfceResourceType type,
* The caller is responsible to free the returned string array using g_strfreev()
* when no longer needed.
*
- * Return value:
+ * Return value: (transfer full): list of possible resources for @type.
*
* Since: 4.2
**/
@@ -589,7 +589,7 @@ xfce_resource_lookup_all (XfceResourceType type,
* Example: xfce_resource_match (XFCE_RESOURCE_CONFIG, "foo/bar*") will probably
* return ("foo/bar", "foo/barbaz", ...).
*
- * Return value: string array of all the relative paths whose names matches the
+ * Return value: (transfer full): string array of all the relative paths whose names matches the
* given @pattern. The return value has to be freed using
* g_strfreev() when no longer needed.
*
@@ -631,15 +631,14 @@ xfce_resource_match (XfceResourceType type,
* xfce_resource_match_custom:
* @type : type of the resource to locate directories for.
* @unique : if %TRUE, only return items which have unique suffixes.
- * @func :
- * @user_data :
+ * @func : (scope call) : callback to determine if there was a match
+ * @user_data : caller defined data
*
* Yet to be implemented!
*
- * The caller is responsible to free the returned string array using g_strfreev()
- * when no longer needed.
*
- * Return value:
+ * Return value: (transfer full): The caller is responsible to free
+ * the returned string array using g_strfreev() when no longer needed.
*
* Since: 4.2
**/
@@ -752,7 +751,7 @@ xfce_resource_pop_path (XfceResourceType type)
* the base path for saving files of the specified @type, though normally
* you should not need this.
*
- * Return value: the path where resources of the specified @type should be
+ * Return value: (transfer full): the path where resources of the specified @type should be
* saved or %NULL on error. The returned string should be freed
* when no longer needed.
*
--
To stop receiving notification emails like this one, please contact
the administrator of this repository.
More information about the Xfce4-commits
mailing list