[rhythmbox] fix various gtk-doc problems, add docs for rb-file-helpers and rb-util
- From: Jonathan Matthew <jmatthew src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [rhythmbox] fix various gtk-doc problems, add docs for rb-file-helpers and rb-util
- Date: Mon, 22 Mar 2010 11:41:27 +0000 (UTC)
commit fce85b08dd7b26d2fd1c7cc45553620839ac11fd
Author: Jonathan Matthew <jonathan d14n org>
Date: Mon Mar 22 21:39:09 2010 +1000
fix various gtk-doc problems, add docs for rb-file-helpers and rb-util
backends/rb-encoder.c | 2 +
doc/reference/rhythmbox-docs.sgml | 1 +
doc/reference/rhythmbox-sections.txt | 58 ++++---
doc/reference/rhythmbox.types | 2 +
lib/rb-debug.c | 8 +-
lib/rb-file-helpers.c | 311 +++++++++++++++++++++++++++++++---
lib/rb-file-helpers.h | 4 +-
lib/rb-stock-icons.c | 13 ++
lib/rb-string-value-map.c | 6 +-
lib/rb-util.c | 288 ++++++++++++++++++++++++++++++--
rhythmdb/rhythmdb.c | 2 +-
shell/rb-play-order.c | 6 +-
shell/rb-plugin.c | 121 +++++++++++++-
shell/rb-plugin.h | 14 +-
shell/rb-shell.c | 61 +++++++-
shell/rb-source-header.c | 16 ++
sources/rb-removable-media-source.c | 2 +-
sources/rb-source-group.c | 4 +-
sources/rb-source.c | 4 +-
sources/rb-sourcelist.c | 2 +
widgets/rb-rating.c | 15 ++
widgets/rb-search-entry.c | 6 +-
22 files changed, 868 insertions(+), 78 deletions(-)
---
diff --git a/backends/rb-encoder.c b/backends/rb-encoder.c
index 60d483b..a533a62 100644
--- a/backends/rb-encoder.c
+++ b/backends/rb-encoder.c
@@ -199,6 +199,8 @@ rb_encoder_get_type (void)
/**
* rb_encoder_factory_get:
*
+ * Returns the #RBEncoderFactory instance.
+ *
* Return value: the #RBEncoderFactory
*/
RBEncoderFactory *
diff --git a/doc/reference/rhythmbox-docs.sgml b/doc/reference/rhythmbox-docs.sgml
index d0f0922..af64885 100644
--- a/doc/reference/rhythmbox-docs.sgml
+++ b/doc/reference/rhythmbox-docs.sgml
@@ -47,6 +47,7 @@
<xi:include href="xml/rb-play-order.xml"/>
<xi:include href="xml/rb-play-order-random.xml"/>
<xi:include href="xml/rb-playlist-manager.xml"/>
+ <xi:include href="xml/rb-plugin.xml"/>
<xi:include href="xml/rb-removable-media-manager.xml"/>
<xi:include href="xml/rb-shell-clipboard.xml"/>
<xi:include href="xml/rb-shell-player.xml"/>
diff --git a/doc/reference/rhythmbox-sections.txt b/doc/reference/rhythmbox-sections.txt
index 90ade41..8f0a083 100644
--- a/doc/reference/rhythmbox-sections.txt
+++ b/doc/reference/rhythmbox-sections.txt
@@ -1026,10 +1026,13 @@ CONF_STATE_BURN_DEVICE
<SECTION>
<FILE>rb-file-helpers</FILE>
rb_file
-rb_dot_dir
+rb_user_data_dir
+rb_user_cache_dir
rb_music_dir
-rb_canonicalise_uri
-rb_uri_mkstemp
+rb_find_user_data_file
+rb_find_user_cache_file
+rb_file_helpers_init
+rb_file_helpers_shutdown
rb_uri_resolve_symlink
rb_uri_is_directory
rb_uri_exists
@@ -1039,15 +1042,25 @@ rb_uri_is_local
rb_uri_is_hidden
rb_uri_could_be_podcast
rb_uri_make_hidden
-rb_uri_get_dir_name
-rb_uri_get_short_path_name
-RBUriRecurseFunc
rb_uri_handle_recursively
rb_uri_handle_recursively_async
+rb_uri_mkstemp
+rb_canonicalise_uri
rb_uri_append_path
rb_uri_append_uri
-rb_file_helpers_init
-rb_file_helpers_shutdown
+rb_uri_get_dir_name
+rb_uri_get_short_path_name
+rb_check_dir_has_space
+rb_check_dir_has_space_uri
+rb_uri_get_mount_point
+rb_uri_create_parent_dirs
+rb_file_find_extant_parent
+rb_uri_get_filesystem_type
+rb_sanitize_path_for_msdos_filesystem
+rb_sanitize_uri_for_filesystem
+RBUriRecurseFunc
+<SUBSECTION Private>
+rb_dot_dir
</SECTION>
<SECTION>
@@ -1058,32 +1071,34 @@ rb_null_function
rb_copy_function
rb_gvalue_compare
rb_compare_gtimeval
-rb_safe_strcmp
-rb_make_duration_string
-rb_make_elapsed_time_string
-rb_gtk_action_popup_menu
rb_image_new_from_stock
-rb_uri_get_mount_point
-rb_threads_init
+rb_gtk_action_popup_menu
rb_is_main_thread
-rb_search_fold
+rb_assert_locked
+rb_threads_init
rb_string_split_words
+rb_search_fold
+rb_make_duration_string
+rb_make_elapsed_time_string
rb_string_list_equal
-rb_string_list_contains
rb_string_list_copy
-rb_list_deep_free
+rb_string_list_contains
rb_list_destroy_free
+rb_list_deep_free
rb_slist_deep_free
-rb_str_in_strv
rb_collate_hash_table_keys
rb_collate_hash_table_values
rb_uri_list_parse
rb_mime_get_friendly_name
rb_signal_accumulator_object_handled
+rb_signal_accumulator_value_array
rb_value_array_append_data
rb_value_free
-rb_assert_locked
+rb_str_in_strv
rb_set_tree_view_column_fixed_width
+rb_scale_pixbuf_to_size
+<SUBSECTION Private>
+rb_safe_strcmp
</SECTION>
<SECTION>
@@ -1186,7 +1201,9 @@ RB_LIBRARY_BROWSER_GET_CLASS
<SECTION>
<FILE>rb-plugin</FILE>
-RB_PLUGIN_CONST
+<TITLE>RBPlugin</TITLE>
+RBPlugin
+RBPluginClass
RBPluginActivationFunc
RBPluginWidgetFunc
RBPluginBooleanFunc
@@ -1207,6 +1224,7 @@ rb_plugin_get_type
RB_PLUGIN_CLASS
RB_IS_PLUGIN_CLASS
RB_PLUGIN_GET_CLASS
+RB_PLUGIN_CONST
</SECTION>
<SECTION>
diff --git a/doc/reference/rhythmbox.types b/doc/reference/rhythmbox.types
index 23c98d5..b78c882 100644
--- a/doc/reference/rhythmbox.types
+++ b/doc/reference/rhythmbox.types
@@ -30,6 +30,7 @@
#include "rb-play-order.h"
#include "rb-play-order-random.h"
#include "rb-play-queue-source.h"
+#include "rb-plugin.h"
#include "rb-preferences.h"
#include "rb-property-view.h"
#include "rb-query-creator.h"
@@ -89,6 +90,7 @@ rb_playlist_manager_get_type
rb_playlist_source_get_type
rb_play_order_get_type
rb_play_queue_source_get_type
+rb_plugin_get_type
rb_property_view_get_type
rb_query_creator_get_type
rb_random_play_order_get_type
diff --git a/lib/rb-debug.c b/lib/rb-debug.c
index 49102c8..b45eead 100644
--- a/lib/rb-debug.c
+++ b/lib/rb-debug.c
@@ -62,8 +62,9 @@ static const char *debug_match = NULL;
* @func: function to check
* @file: filename to check
*
- * Return value: TRUE if @func or @file match the current
- * debug output settings.
+ * Checks if @file or @func matches the current debug output settings.
+ *
+ * Return value: %TRUE if matched
*/
gboolean
rb_debug_matches (const char *func,
@@ -80,7 +81,7 @@ rb_debug_matches (const char *func,
/**
* rb_debug:
- * @...: printf-style format string followed by any substitution values
+ * @Varargs: printf-style format string followed by any substitution values
*
* If the call site function or file name matches the current debug output
* settings, the message will be formatted and printed to standard error,
@@ -96,6 +97,7 @@ rb_debug_matches (const char *func,
* @line: line number
* @newline: if TRUE, add a newline to the output
* @format: printf style format specifier
+ * @Varargs: substitution values for @format
*
* If the debug output settings match the function or file names,
* the debug message will be formatted and written to standard error.
diff --git a/lib/rb-file-helpers.c b/lib/rb-file-helpers.c
index 5466b8d..cc62652 100644
--- a/lib/rb-file-helpers.c
+++ b/lib/rb-file-helpers.c
@@ -25,6 +25,15 @@
*
*/
+/**
+ * SECTION:rb-file-helpers
+ * @short_description: An assortment of file and URI helper functions
+ *
+ * This is a variety of functions for dealing with files and URIs, including
+ * locating installed files, finding user cache and config directories,
+ * and dealing with file naming restrictions for various filesystems.
+ */
+
#include <gtk/gtk.h>
#include <glib.h>
#include <glib/gi18n.h>
@@ -66,6 +75,15 @@ static char *installed_paths[] = {
static char **search_paths;
+/**
+ * rb_file:
+ * @filename: name of file to search for
+ *
+ * Searches for an installed file, returning the full path name
+ * if found, NULL otherwise.
+ *
+ * Return value: Full file name, if found. Must not be freed.
+ */
const char *
rb_file (const char *filename)
{
@@ -90,6 +108,13 @@ rb_file (const char *filename)
return NULL;
}
+/**
+ * rb_dot_dir:
+ *
+ * Deprecated.
+ *
+ * Return value: user's ~/.gnome2/rhythmbox/ dir
+ */
const char *
rb_dot_dir (void)
{
@@ -156,6 +181,14 @@ rb_user_cache_dir (void)
}
+/**
+ * rb_music_dir:
+ *
+ * Returns the default directory for the user's music library.
+ * This will usually be the 'Music' directory under the home directory.
+ *
+ * Return value: user's music directory. must not be freed.
+ */
const char *
rb_music_dir (void)
{
@@ -272,6 +305,13 @@ rb_find_user_cache_file (const char *name,
return rb_find_user_file (rb_user_cache_dir (), name, error);
}
+/**
+ * rb_file_helpers_init:
+ * @uninstalled: if %TRUE, search in source and build directories
+ * as well as installed locations
+ *
+ * Sets up file search paths for @rb_file. Must be called on startup.
+ */
void
rb_file_helpers_init (gboolean uninstalled)
{
@@ -286,6 +326,12 @@ rb_file_helpers_init (gboolean uninstalled)
(GDestroyNotify) g_free);
}
+/**
+ * rb_file_helpers_shutdown:
+ *
+ * Frees various data allocated by file helper functions.
+ * Should be called on shutdown.
+ */
void
rb_file_helpers_shutdown (void)
{
@@ -299,6 +345,16 @@ rb_file_helpers_shutdown (void)
/* not sure this is really useful */
+/**
+ * rb_uri_resolve_symlink:
+ * @uri: the URI to process
+ * @error: returns error information
+ *
+ * Attempts to resolve symlinks in @uri and return a canonical URI for the file
+ * it identifies.
+ *
+ * Return value: resolved URI, or NULL on error
+ */
char *
rb_uri_resolve_symlink (const char *uri, GError **error)
{
@@ -382,6 +438,14 @@ rb_uri_resolve_symlink (const char *uri, GError **error)
return result;
}
+/**
+ * rb_uri_is_directory:
+ * @uri: the URI to check
+ *
+ * Checks if @uri identifies a directory.
+ *
+ * Return value: %TRUE if @uri is a directory
+ */
gboolean
rb_uri_is_directory (const char *uri)
{
@@ -402,6 +466,14 @@ rb_uri_is_directory (const char *uri)
return (ftype == G_FILE_TYPE_DIRECTORY);
}
+/**
+ * rb_uri_exists:
+ * @uri: a URI to check
+ *
+ * Checks if a URI identifies a resource that exists
+ *
+ * Return value: %TRUE if @uri exists
+ */
gboolean
rb_uri_exists (const char *uri)
{
@@ -438,30 +510,76 @@ get_uri_perm (const char *uri, const char *perm_attribute)
return result;
}
+/**
+ * rb_uri_is_readable:
+ * @uri: a URI to check
+ *
+ * Checks if the user can read the resource identified by @uri
+ *
+ * Return value: %TRUE if @uri is readable
+ */
gboolean
-rb_uri_is_readable (const char *text_uri)
+rb_uri_is_readable (const char *uri)
{
- return get_uri_perm (text_uri, G_FILE_ATTRIBUTE_ACCESS_CAN_READ);
+ return get_uri_perm (uri, G_FILE_ATTRIBUTE_ACCESS_CAN_READ);
}
+/**
+ * rb_uri_is_writable:
+ * @uri: a URI to check
+ *
+ * Checks if the user can write to the resource identified by @uri
+ *
+ * Return value: %TRUE if @uri is writable
+ */
gboolean
-rb_uri_is_writable (const char *text_uri)
+rb_uri_is_writable (const char *uri)
{
- return get_uri_perm (text_uri, G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE);
+ return get_uri_perm (uri, G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE);
}
+/**
+ * rb_uri_is_local:
+ * @uri: a URI to check
+ *
+ * Checks if @uri identifies a local resource. Currently this just
+ * checks that it uses the 'file' URI scheme.
+ *
+ * Return value: %TRUE if @uri is local
+ */
gboolean
-rb_uri_is_local (const char *text_uri)
+rb_uri_is_local (const char *uri)
{
- return g_str_has_prefix (text_uri, "file://");
+ return g_str_has_prefix (uri, "file://");
}
+/**
+ * rb_uri_is_hidden:
+ * @uri: a URI to check
+ *
+ * Checks if @uri is hidden, according to the Unix filename convention.
+ * If the filename component of @uri begins with a dot, the file is considered
+ * hidden.
+ *
+ * Return value: %TRUE if @uri is hidden
+ */
gboolean
-rb_uri_is_hidden (const char *text_uri)
+rb_uri_is_hidden (const char *uri)
{
- return g_utf8_strrchr (text_uri, -1, '/')[1] == '.';
+ return g_utf8_strrchr (uri, -1, '/')[1] == '.';
}
+/**
+ * rb_uri_could_be_podcast:
+ * @uri: a URI to check
+ * @is_opml: returns whether the URI identifies an OPML document
+ *
+ * Checks if @uri identifies a resource that is probably a podcast
+ * (RSS or Atom feed). This does not perform any IO, it just guesses
+ * based on the URI itself.
+ *
+ * Return value: %TRUE if @uri may be a podcast
+ */
gboolean
rb_uri_could_be_podcast (const char *uri, gboolean *is_opml)
{
@@ -527,8 +645,18 @@ rb_uri_could_be_podcast (const char *uri, gboolean *is_opml)
return FALSE;
}
+/**
+ * rb_uri_make_hidden:
+ * @uri: a URI to construct a hidden version of
+ *
+ * Constructs a URI that is similar to @uri but which identifies
+ * a hidden file. This can be used for temporary files that should not
+ * be visible to the user while they are in use.
+ *
+ * Return value: hidden URI, must be freed by the caller.
+ */
char *
-rb_uri_make_hidden (const char *text_uri)
+rb_uri_make_hidden (const char *uri)
{
GFile *file;
GFile *parent;
@@ -536,10 +664,10 @@ rb_uri_make_hidden (const char *text_uri)
char *dotted;
char *ret = NULL;
- if (rb_uri_is_hidden (text_uri))
- return g_strdup (text_uri);
+ if (rb_uri_is_hidden (uri))
+ return g_strdup (uri);
- file = g_file_new_for_uri (text_uri);
+ file = g_file_new_for_uri (uri);
shortname = g_file_get_basename (file);
if (shortname == NULL) {
@@ -697,8 +825,18 @@ _uri_handle_recurse (GFile *dir,
g_object_unref (files);
}
+/**
+ * rb_uri_handle_recursively:
+ * @uri: URI to visit
+ * @cancel: an optional #GCancellable to allow cancellation
+ * @func: Callback function
+ * @user_data: Data for callback function
+ *
+ * Calls @func for each file found under the directory identified by @uri.
+ * If @uri identifies a file, calls @func for that instead.
+ */
void
-rb_uri_handle_recursively (const char *text_uri,
+rb_uri_handle_recursively (const char *uri,
GCancellable *cancel,
RBUriRecurseFunc func,
gpointer user_data)
@@ -706,7 +844,7 @@ rb_uri_handle_recursively (const char *text_uri,
GFile *file;
GHashTable *handled;
- file = g_file_new_for_uri (text_uri);
+ file = g_file_new_for_uri (uri);
handled = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, NULL);
_uri_handle_recurse (file, cancel, handled, func, user_data);
@@ -805,8 +943,26 @@ _recurse_async_func (RBUriHandleRecursivelyAsyncData *data)
return NULL;
}
+/**
+ * rb_uri_handle_recursively_async:
+ * @uri: the URI to visit
+ * @cancel: a #GCancellable to allow cancellation
+ * @func: callback function
+ * @user_data: data to pass to callback
+ * @data_destroy: function to call to free @user_data
+ *
+ * Calls @func for each file found under the directory identified
+ * by @uri, or if @uri identifies a file, calls it once
+ * with that.
+ *
+ * Directory recursion happens on a separate thread, but the callbacks
+ * are called on the main thread.
+ *
+ * If non-NULL, @destroy_data will be called once all files have been
+ * processed, or when the operation is cancelled.
+ */
void
-rb_uri_handle_recursively_async (const char *text_uri,
+rb_uri_handle_recursively_async (const char *uri,
GCancellable *cancel,
RBUriRecurseFunc func,
gpointer user_data,
@@ -814,7 +970,7 @@ rb_uri_handle_recursively_async (const char *text_uri,
{
RBUriHandleRecursivelyAsyncData *data = g_new0 (RBUriHandleRecursivelyAsyncData, 1);
- data->uri = g_strdup (text_uri);
+ data->uri = g_strdup (uri);
data->user_data = user_data;
if (cancel != NULL) {
data->cancel = g_object_ref (cancel);
@@ -828,6 +984,18 @@ rb_uri_handle_recursively_async (const char *text_uri,
g_thread_create ((GThreadFunc)_recurse_async_func, data, FALSE, NULL);
}
+/**
+ * rb_uri_mkstemp:
+ * @prefix: URI prefix
+ * @uri_ret: returns the temporary file URI
+ * @stream: returns a @GOutputStream for the temporary file
+ * @error: returns error information
+ *
+ * Creates a temporary file whose URI begins with @prefix, returning
+ * the file URI and an output stream for writing to it.
+ *
+ * Return value: %TRUE if successful
+ */
gboolean
rb_uri_mkstemp (const char *prefix, char **uri_ret, GOutputStream **stream, GError **error)
{
@@ -860,7 +1028,16 @@ rb_uri_mkstemp (const char *prefix, char **uri_ret, GOutputStream **stream, GErr
}
}
-
+/**
+ * rb_canonicalise_uri:
+ * @uri: URI to canonicalise
+ *
+ * Converts @uri to canonical URI form, ensuring it doesn't contain
+ * any redundant directory fragments or unnecessarily escaped characters.
+ * All URIs passed to #RhythmDB functions should be canonicalised.
+ *
+ * Return value: canonical URI, must be freed by caller
+ */
char *
rb_canonicalise_uri (const char *uri)
{
@@ -877,6 +1054,15 @@ rb_canonicalise_uri (const char *uri)
return result;
}
+/**
+ * rb_uri_append_path:
+ * @uri: the URI to append to
+ * @path: the path fragment to append
+ *
+ * Creates a new URI consisting of @path appended to @uri.
+ *
+ * Return value: new URI, must be freed by caller
+ */
char*
rb_uri_append_path (const char *uri, const char *path)
{
@@ -900,6 +1086,16 @@ rb_uri_append_path (const char *uri, const char *path)
return result;
}
+/**
+ * rb_uri_append_uri:
+ * @uri: the URI to append to
+ * @fragment: the URI fragment to append
+ *
+ * Creates a new URI consisting of @fragment appended to @uri.
+ * Generally isn't a good idea.
+ *
+ * Return value: new URI, must be freed by caller
+ */
char*
rb_uri_append_uri (const char *uri, const char *fragment)
{
@@ -920,6 +1116,15 @@ rb_uri_append_uri (const char *uri, const char *fragment)
return rv;
}
+/**
+ * rb_uri_get_dir_name:
+ * @uri: a URI
+ *
+ * Returns the directory component of @uri, that is, everything up
+ * to the start of the filename.
+ *
+ * Return value: new URI for parent of @uri, must be freed by caller.
+ */
char *
rb_uri_get_dir_name (const char *uri)
{
@@ -937,6 +1142,15 @@ rb_uri_get_dir_name (const char *uri)
return dirname;
}
+/**
+ * rb_uri_get_short_path_name:
+ * @uri: a URI
+ *
+ * Returns the filename component of @uri, that is, everything after the
+ * final slash and before the start of the query string or fragment.
+ *
+ * Return value: filename component of @uri, must be freed by caller
+ */
char *
rb_uri_get_short_path_name (const char *uri)
{
@@ -973,8 +1187,18 @@ rb_uri_get_short_path_name (const char *uri)
}
}
+/**
+ * rb_check_dir_has_space:
+ * @dir: a #GFile to check
+ * @bytes_needed: number of bytes to check for
+ *
+ * Checks that the filesystem holding @file has at least @bytes_needed
+ * bytes available.
+ *
+ * Return value: %TRUE if enough space is available.
+ */
gboolean
-rb_check_dir_has_space (GFile *file,
+rb_check_dir_has_space (GFile *dir,
guint64 bytes_needed)
{
GFile *extant;
@@ -982,9 +1206,9 @@ rb_check_dir_has_space (GFile *file,
GError *error = NULL;
guint64 free_bytes;
- extant = rb_file_find_extant_parent (file);
+ extant = rb_file_find_extant_parent (dir);
if (extant == NULL) {
- char *uri = g_file_get_uri (file);
+ char *uri = g_file_get_uri (dir);
g_warning ("Cannot get free space at %s: none of the directory structure exists", uri);
g_free (uri);
return FALSE;
@@ -998,7 +1222,7 @@ rb_check_dir_has_space (GFile *file,
if (error != NULL) {
char *uri;
- uri = g_file_get_uri (file);
+ uri = g_file_get_uri (dir);
g_warning (_("Cannot get free space at %s: %s"), uri, error->message);
g_free (uri);
return FALSE;
@@ -1013,6 +1237,16 @@ rb_check_dir_has_space (GFile *file,
return TRUE;
}
+/**
+ * rb_check_dir_has_space_uri:
+ * @uri: a URI to check
+ * @bytes_needed: number of bytes to check for
+ *
+ * Checks that the filesystem holding @uri has at least @bytes_needed
+ * bytes available.
+ *
+ * Return value: %TRUE if enough space is available.
+ */
gboolean
rb_check_dir_has_space_uri (const char *uri,
guint64 bytes_needed)
@@ -1027,6 +1261,17 @@ rb_check_dir_has_space_uri (const char *uri,
return result;
}
+/**
+ * rb_uri_get_mount_point:
+ * @uri: a URI
+ *
+ * Returns the mount point of the filesystem holding @uri.
+ * If @uri is on a normal filesystem mount (such as /, /home,
+ * /var, etc.) this will be NULL.
+ *
+ * Return value: filesystem mount point (must be freed by caller)
+ * or NULL.
+ */
gchar *
rb_uri_get_mount_point (const char *uri)
{
@@ -1083,6 +1328,16 @@ check_file_is_directory (GFile *file, GError **error)
}
+/**
+ * rb_uri_create_parent_dirs:
+ * @uri: a URI for which to create parent directories
+ * @error: returns error information
+ *
+ * Ensures that all parent directories of @uri exist so that
+ * @uri itself can be created directly.
+ *
+ * Return value: %TRUE if successful
+ */
gboolean
rb_uri_create_parent_dirs (const char *uri, GError **error)
{
@@ -1149,7 +1404,9 @@ rb_file_find_extant_parent (GFile *file)
* rb_uri_get_filesystem_type:
* @uri: URI to get filesystem type for
*
- * Return value: a string describing the type of the filesystem containing the URI
+ * Returns a string describing the type of the filesystem containing @uri.
+ *
+ * Return value: filesystem type string, must be freed by caller.
*/
char *
rb_uri_get_filesystem_type (const char *uri)
@@ -1193,6 +1450,9 @@ rb_uri_get_filesystem_type (const char *uri)
/**
* rb_sanitize_path_for_msdos_filesystem:
* @path: a path to sanitize (modified in place)
+ *
+ * Modifies @path such that it represents a legal path for MS DOS
+ * filesystems.
*/
void
rb_sanitize_path_for_msdos_filesystem (char *path)
@@ -1205,8 +1465,11 @@ rb_sanitize_path_for_msdos_filesystem (char *path)
* rb_sanitize_uri_for_filesystem:
* @uri: a URI to sanitize
*
- * Return value: a copy of the URI with characters not allowed by the target filesystem
- * replaced
+ * Removes characters from @uri that are not allowed by the filesystem
+ * on which it would be stored. At present, this only supports MS DOS
+ * filesystems.
+ *
+ * Return value: sanitized copy of @uri, must be freed by caller.
*/
char *
rb_sanitize_uri_for_filesystem (const char *uri)
diff --git a/lib/rb-file-helpers.h b/lib/rb-file-helpers.h
index e3cd794..914bbb3 100644
--- a/lib/rb-file-helpers.h
+++ b/lib/rb-file-helpers.h
@@ -46,8 +46,8 @@ char * rb_find_user_cache_file (const char *name,
char * rb_canonicalise_uri (const char *uri);
-gboolean rb_uri_mkstemp (const char *prefix, char **uri,
- GOutputStream **handle, GError **error);
+gboolean rb_uri_mkstemp (const char *prefix, char **uri_ret,
+ GOutputStream **stream, GError **error);
char * rb_uri_resolve_symlink (const char *uri, GError **error);
gboolean rb_uri_is_directory (const char *uri);
diff --git a/lib/rb-stock-icons.c b/lib/rb-stock-icons.c
index 50a5504..3b9339e 100644
--- a/lib/rb-stock-icons.c
+++ b/lib/rb-stock-icons.c
@@ -70,6 +70,12 @@ static RBInlineIconData inline_icons[] = {
{ rhythmbox_no_star_inline, RB_STOCK_NO_STAR }
};
+/**
+ * rb_stock_icons_init:
+ *
+ * Initializes the stock icons, adding the necessary filesystem
+ * locations to the GTK icon search path. Must be called on startup.
+ */
void
rb_stock_icons_init (void)
{
@@ -111,6 +117,13 @@ rb_stock_icons_init (void)
}
}
+/**
+ * rb_stock_icons_shutdown:
+ *
+ * If anything was necessary to clean up the stock icons, this function
+ * would do it. Doesn't do anything, but should be called on shutdown
+ * anyway.
+ */
void
rb_stock_icons_shutdown (void)
{
diff --git a/lib/rb-string-value-map.c b/lib/rb-string-value-map.c
index c25e924..3130f06 100644
--- a/lib/rb-string-value-map.c
+++ b/lib/rb-string-value-map.c
@@ -84,6 +84,8 @@ rb_string_value_map_finalize (GObject *obj)
/**
* rb_string_value_map_new:
*
+ * Creates a new #RBStringValueMap
+ *
* Return value: new empty #RBStringValueMap
*/
RBStringValueMap*
@@ -134,7 +136,9 @@ rb_string_value_map_remove (RBStringValueMap *map,
* rb_string_value_map_size:
* @map: a #RBStringValueMap
*
- * Return value: the number of entries in the map
+ * Returns the number of entries in the map.
+ *
+ * Return value: number of entries
*/
guint
rb_string_value_map_size (RBStringValueMap *map)
diff --git a/lib/rb-util.c b/lib/rb-util.c
index 7c6d256..2d437a3 100644
--- a/lib/rb-util.c
+++ b/lib/rb-util.c
@@ -25,6 +25,16 @@
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
*/
+
+/**
+ * SECTION:rb-util
+ * @short_description: assorted utility functions
+ *
+ * This is a dumping ground for utility functions that may or may not
+ * be generally useful in Rhythmbox or elsewhere. Things end up here
+ * if they're clever or if they're used all over the place.
+ */
+
#include "config.h"
#include <string.h>
@@ -41,24 +51,56 @@
static GPrivate * private_is_primary_thread;
+/**
+ * rb_true_function:
+ * @dummy: unused
+ *
+ * Just returns %TRUE, useful as a callback function.
+ *
+ * Return value: %TRUE
+ */
gboolean
rb_true_function (gpointer dummy)
{
return TRUE;
}
+/**
+ * rb_false_function:
+ * @dummy: unused
+ *
+ * Just returns %FALSE, useful as a callback function.
+ *
+ * Return value: %FALSE
+ */
gboolean
rb_false_function (gpointer dummy)
{
return FALSE;
}
+/**
+ * rb_null_function:
+ * @dummy: unused
+ *
+ * Just returns NULL. Useful as a callback function.
+ *
+ * Return value: NULL
+ */
gpointer
rb_null_function (gpointer dummy)
{
return NULL;
}
+/**
+ * rb_copy_function:
+ * @data: generic argument
+ *
+ * Just returns its first argument. Useful as a callback function.
+ *
+ * Return value: @data
+ */
gpointer
rb_copy_function (gpointer data)
{
@@ -66,6 +108,17 @@ rb_copy_function (gpointer data)
}
+/**
+ * rb_gvalue_compare:
+ * @a: left hand side
+ * @b: right hand size
+ *
+ * Compares @a and @b for sorting. @a and @b must contain the same value
+ * type for the comparison to be valid. Comparisons for some value types
+ * are not particularly useful.
+ *
+ * Return value: -1 if @a < @b, 0 if @a == @b, 1 if @a > @b
+ */
int
rb_gvalue_compare (GValue *a, GValue *b)
{
@@ -207,6 +260,15 @@ rb_gvalue_compare (GValue *a, GValue *b)
return retval;
}
+/**
+ * rb_compare_gtimeval:
+ * @a: left hand side
+ * @b: right hand size
+ *
+ * Compares two #GTimeval structures for sorting.
+ *
+ * Return value: -1 if @a < @b, 0 if @a == @b, 1 if @a > @b
+ */
int
rb_compare_gtimeval (GTimeVal *a, GTimeVal *b)
{
@@ -222,6 +284,7 @@ rb_compare_gtimeval (GTimeVal *a, GTimeVal *b)
return -1;
}
+/* this is obsoleted by g_strcmp0, don't use it */
int
rb_safe_strcmp (const char *a,
const char *b)
@@ -266,8 +329,15 @@ totem_pixbuf_mirror (GdkPixbuf *pixbuf)
-/* Same as gtk_image_new_from_stock except that it mirrors the icons for RTL
- * languages
+/**
+ * rb_image_new_from_stock:
+ * @stock_id: stock image id
+ * @size: requested icon size
+ *
+ * Same as @gtk_image_new_from_stock except that it mirrors the icons for RTL
+ * languages.
+ *
+ * Return value: a #GtkImage of the requested stock item
*/
GtkWidget *
rb_image_new_from_stock (const gchar *stock_id, GtkIconSize size)
@@ -306,6 +376,14 @@ rb_image_new_from_stock (const gchar *stock_id, GtkIconSize size)
return NULL;
}
+/**
+ * rb_gtk_action_popup_menu:
+ * @uimanager: a #GtkUIManager
+ * @path: UI path for the popup to display
+ *
+ * Simple shortcut for getting a popup menu from a #GtkUIManager and
+ * displaying it.
+ */
void
rb_gtk_action_popup_menu (GtkUIManager *uimanager, const char *path)
{
@@ -320,7 +398,13 @@ rb_gtk_action_popup_menu (GtkUIManager *uimanager, const char *path)
}
}
-
+/**
+ * rb_is_main_thread:
+ *
+ * Checks if currently executing on the main thread.
+ *
+ * Return value: %TRUE if on the main thread
+ */
gboolean
rb_is_main_thread (void)
{
@@ -355,13 +439,25 @@ _threads_leave (void)
}
+/**
+ * rb_assert_locked:
+ * @mutex: a #GMutex
+ *
+ * Asserts that @mutex is currently locked. Does not work with all
+ * mutex implementations.
+ */
void
-rb_assert_locked (GMutex *m)
+rb_assert_locked (GMutex *mutex)
{
if (!mutex_recurses)
- g_assert (!g_mutex_trylock (m));
+ g_assert (!g_mutex_trylock (mutex));
}
+/**
+ * rb_threads_init:
+ *
+ * Initializes various thread helpers. Must be called on startup.
+ */
void
rb_threads_init (void)
{
@@ -389,6 +485,14 @@ rb_threads_init (void)
g_timeout_add_seconds (30, purge_useless_threads, NULL);
}
+/**
+ * rb_string_split_words:
+ * @string: the string to split
+ *
+ * Splits @string on word boundaries using Unicode character definitions.
+ *
+ * Return value: NULL-terminated array of strings, must be freed by caller (see @g_strfreev)
+ */
gchar **
rb_string_split_words (const gchar *string)
{
@@ -494,6 +598,15 @@ rb_string_split_words (const gchar *string)
return ret;
}
+/**
+ * rb_search_fold:
+ * @original: the string to fold
+ *
+ * Returns a case-folded and punctuation-stripped version of @original, useful
+ * for performing text searches.
+ *
+ * Return value: case-folded string, must be freed by caller.
+ */
gchar*
rb_search_fold (const char *original)
{
@@ -560,6 +673,15 @@ rb_search_fold (const char *original)
return g_string_free (string, FALSE);
}
+/**
+ * rb_make_duration_string:
+ * @duration: duration in seconds
+ *
+ * Constructs a string describing the specified duration. The string
+ * describes hours, minutes, and seconds, and its format is localised.
+ *
+ * Return value: duration string, must be freed by caller.
+ */
char *
rb_make_duration_string (guint duration)
{
@@ -580,6 +702,18 @@ rb_make_duration_string (guint duration)
return str;
}
+/**
+ * rb_make_elapsed_time_string:
+ * @elapsed: elapsed time (in seconds)
+ * @duration: duration (in seconds)
+ * @show_remaining: if %TRUE, show the remaining time, otherwise show elapsed time
+ *
+ * Constructs a string describing a playback position. The string describes hours,
+ * minutes, and seconds, and its format is localised. The string can describe either
+ * the elapsed time or the time remaining.
+ *
+ * Return value: elapsed/remaining time string, must be freed by caller
+ */
char *
rb_make_elapsed_time_string (guint elapsed, guint duration, gboolean show_remaining)
{
@@ -629,6 +763,16 @@ rb_make_elapsed_time_string (guint elapsed, guint duration, gboolean show_remain
}
}
+/**
+ * rb_string_list_equal:
+ * @a: list of strings to compare
+ * @b: other list of strings to compare
+ *
+ * Checks if @a and @b contain exactly the same set of strings,
+ * regardless of order.
+ *
+ * Return value: %TRUE if the lists contain all the same strings
+ */
gboolean
rb_string_list_equal (GList *a, GList *b)
{
@@ -674,6 +818,15 @@ list_copy_cb (const char *s, GList **list)
*list = g_list_prepend (*list, g_strdup (s));
}
+/**
+ * rb_string_list_copy:
+ * @list: list of strings to copy
+ *
+ * Creates a deep copy of @list.
+ *
+ * Return value: copied list, must be freed (and its contents freed)
+ * by caller
+ */
GList *
rb_string_list_copy (GList *list)
{
@@ -688,6 +841,15 @@ rb_string_list_copy (GList *list)
return copy;
}
+/**
+ * rb_string_list_contains:
+ * @list: list to check
+ * @s: string to check for
+ *
+ * Checks if @list contains the string @s.
+ *
+ * Return value: %TRUE if found
+ */
gboolean
rb_string_list_contains (GList *list, const char *s)
{
@@ -701,20 +863,38 @@ rb_string_list_contains (GList *list, const char *s)
return FALSE;
}
+/**
+ * rb_list_destroy_free:
+ * @list: list to destroy
+ * @destroyer: function to call to free elements of @list
+ *
+ * Calls @destroyer for each element in @list, then frees @list.
+ */
void
rb_list_destroy_free (GList *list, GDestroyNotify destroyer)
{
g_list_foreach (list, (GFunc)destroyer, NULL);
g_list_free (list);
-
}
+/**
+ * rb_list_deep_free:
+ * @list: list to free
+ *
+ * Frees each element of @list and @list itself.
+ */
void
rb_list_deep_free (GList *list)
{
rb_list_destroy_free (list, (GDestroyNotify)g_free);
}
+/**
+ * rb_slist_deep_free:
+ * @list: list to free
+ *
+ * Frees each element of @list and @list itself.
+ */
void
rb_slist_deep_free (GSList *list)
{
@@ -734,6 +914,15 @@ collate_values_cb (gpointer key, gpointer value, GList **list)
*list = g_list_prepend (*list, value);
}
+/**
+ * rb_collate_hash_table_keys:
+ * @table: #GHashTable to collate
+ *
+ * Returns a #GList containing all keys from @table. The keys are
+ * not copied.
+ *
+ * Return value: #GList of keys, must be freed by caller
+ */
GList*
rb_collate_hash_table_keys (GHashTable *table)
{
@@ -745,6 +934,15 @@ rb_collate_hash_table_keys (GHashTable *table)
return list;
}
+/**
+ * rb_collate_hash_table_values:
+ * @table: #GHashTable to collate
+ *
+ * Returns a #GList containing all values from @table. The values are
+ * not copied.
+ *
+ * Return value: #GList of values, must be freed by caller
+ */
GList*
rb_collate_hash_table_values (GHashTable *table)
{
@@ -756,11 +954,15 @@ rb_collate_hash_table_values (GHashTable *table)
return list;
}
-/*
- * hacked up version of gnome_vfs_uri_list_parse,
- * that it doesn't strip #s and and returns strings.
+/**
+ * rb_uri_list_parse:
+ * @uri_list: string containing URIs to parse
+ *
+ * Converts a single string containing a list of URIs into
+ * a #GList of URI strings.
+ *
+ * Return value: #GList of URI strings, must be deep-freed by caller
*/
-
GList *
rb_uri_list_parse (const char *uri_list)
{
@@ -803,6 +1005,14 @@ rb_uri_list_parse (const char *uri_list)
return g_list_reverse (result);
}
+/**
+ * rb_mime_get_friendly_name:
+ * @mime_type: a MIME type
+ *
+ * Returns a human-friendly description of the MIME type @mime_type.
+ *
+ * Return value: type description, must be freed by caller
+ */
char*
rb_mime_get_friendly_name (const char *mime_type)
{
@@ -811,11 +1021,25 @@ rb_mime_get_friendly_name (const char *mime_type)
if (name == NULL && mime_type)
name = g_content_type_get_description (mime_type);
if (name == NULL)
- name = _("Unknown");
+ name = g_strdup (_("Unknown"));
return name;
}
+/**
+ * rb_signal_accumulator_object_handled:
+ * @hint: a #GSignalInvocationHint
+ * @return_accu: holds the accumulated return value
+ * @handler_return: holds the return value to be accumulated
+ * @dummy: user data (unused)
+ *
+ * A #GSignalAccumulator that aborts the signal emission after the
+ * first handler to return a value, and returns the value returned by
+ * that handler. This is the opposite behaviour from what you get when
+ * no accumulator is specified, where the last signal handler wins.
+ *
+ * Return value: %FALSE to abort signal emission, %TRUE to continue
+ */
gboolean
rb_signal_accumulator_object_handled (GSignalInvocationHint *hint,
GValue *return_accu,
@@ -834,11 +1058,23 @@ rb_signal_accumulator_object_handled (GSignalInvocationHint *hint,
return FALSE;
}
+/**
+ * rb_signal_accumulator_value_array:
+ * @hint: a #GSignalInvocationHint
+ * @return_accu: holds the accumulated return value
+ * @handler_return: holds the return value to be accumulated
+ * @dummy: user data (unused)
+ *
+ * A #GSignalAccumulator used to combine all returned values into
+ * a #GValueArray.
+ *
+ * Return value: %FALSE to abort signal emission, %TRUE to continue
+ */
gboolean
rb_signal_accumulator_value_array (GSignalInvocationHint *hint,
GValue *return_accu,
const GValue *handler_return,
- gpointer bleh)
+ gpointer dummy)
{
GValueArray *a;
GValueArray *b;
@@ -873,6 +1109,14 @@ rb_signal_accumulator_value_array (GSignalInvocationHint *hint,
return TRUE;
}
+/**
+ * rb_value_array_append_data:
+ * @array: #GValueArray to append to
+ * @type: #GType of the value being appended
+ * @Varargs: value to append
+ *
+ * Appends a single value to @array, collecting it from @Varargs.
+ */
void
rb_value_array_append_data (GValueArray *array, GType type, ...)
{
@@ -893,6 +1137,13 @@ rb_value_array_append_data (GValueArray *array, GType type, ...)
va_end (va);
}
+/**
+ * rb_value_free:
+ * @val: a #GValue
+ *
+ * Unsets and frees @val. @val must have been allocated using
+ * @g_slice_new or @g_slice_new0.
+ */
void
rb_value_free (GValue *val)
{
@@ -900,6 +1151,16 @@ rb_value_free (GValue *val)
g_slice_free (GValue, val);
}
+/**
+ * rb_str_in_strv:
+ * @needle: string to search for
+ * @haystack: array of strings to search
+ *
+ * Checks if @needle is present in the NULL-terminated string
+ * array @haystack.
+ *
+ * Return value: %TRUE if found
+ */
gboolean
rb_str_in_strv (const char *needle, char **haystack)
{
@@ -962,6 +1223,8 @@ rb_set_tree_view_column_fixed_width (GtkWidget *treeview,
*
* Creates a new #GdkPixbuf from the original one, for a target of
* size, respecting the aspect ratio of the image.
+ *
+ * Return value: scaled #GdkPixbuf
*/
GdkPixbuf *
rb_scale_pixbuf_to_size (GdkPixbuf *pixbuf, GtkIconSize size)
@@ -988,4 +1251,3 @@ rb_scale_pixbuf_to_size (GdkPixbuf *pixbuf, GtkIconSize size)
return gdk_pixbuf_scale_simple (pixbuf, d_width, d_height, GDK_INTERP_BILINEAR);
}
-
diff --git a/rhythmdb/rhythmdb.c b/rhythmdb/rhythmdb.c
index d459a66..90fd4ec 100644
--- a/rhythmdb/rhythmdb.c
+++ b/rhythmdb/rhythmdb.c
@@ -429,7 +429,7 @@ rhythmdb_class_init (RhythmDBClass *klass)
0);
/**
- * RhythmDB::save-completed:
+ * RhythmDB::save-complete:
* @db: the #RhythmDB
*
* Emitted when the database has been saved.
diff --git a/shell/rb-play-order.c b/shell/rb-play-order.c
index a4192de..c8c099b 100644
--- a/shell/rb-play-order.c
+++ b/shell/rb-play-order.c
@@ -792,8 +792,10 @@ rb_play_order_go_next (RBPlayOrder *porder)
* rb_play_order_has_previous:
* @porder: RBPlayOrder instance
*
- * Returns: true if there is an entry before the current entry in the play order.
- * If not currently playing, returns false.
+ * Returns %TRUE if there is an entry before the current entry in the play order.
+ * If not currently playing, returns %FALSE.
+ *
+ * Return value: %TRUE if previous entry exists
*/
gboolean
rb_play_order_has_previous (RBPlayOrder *porder)
diff --git a/shell/rb-plugin.c b/shell/rb-plugin.c
index 3313756..8aa3e2d 100644
--- a/shell/rb-plugin.c
+++ b/shell/rb-plugin.c
@@ -28,6 +28,14 @@
* Boston, MA 02110-1301 USA.
*/
+/**
+ * SECTION:rb-plugin
+ * @short_description: Base class for plugins
+ *
+ * This is the base class for all plugins. It provides methods called
+ * when activating, deactivating, and configuring plugins.
+ */
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
@@ -150,6 +158,14 @@ rb_plugin_get_property (GObject *object,
}
}
+/**
+ * rb_plugin_activate:
+ * @plugin: the #RBPlugin being activated
+ * @shell: the #RBShell
+ *
+ * Called when a plugin is being activated, either on startup or when
+ * enabled in the plugin configuration dialog.
+ */
void
rb_plugin_activate (RBPlugin *plugin,
RBShell *shell)
@@ -161,6 +177,18 @@ rb_plugin_activate (RBPlugin *plugin,
RB_PLUGIN_GET_CLASS (plugin)->activate (plugin, shell);
}
+/**
+ * rb_plugin_deactivate:
+ * @plugin: the #RBPlugin being deactivated
+ * @shell: the #RBShell
+ *
+ * Called when a plugin is being deactivated, either on shutdown or
+ * when disabled in the plugin configuration dialog.
+ *
+ * Note that plugin instances are never destroyed, so the same plugin
+ * instance can be deactivated and then reactivated. After deactivation,
+ * the plugin must be in a state where it can be reactivated.
+ */
void
rb_plugin_deactivate (RBPlugin *plugin,
RBShell *shell)
@@ -172,6 +200,14 @@ rb_plugin_deactivate (RBPlugin *plugin,
RB_PLUGIN_GET_CLASS (plugin)->deactivate (plugin, shell);
}
+/**
+ * rb_plugin_is_configurable
+ * @plugin: the #RBPlugin
+ *
+ * Determines whether the plugin is configurable.
+ *
+ * Return value: %TRUE if configurable
+ */
gboolean
rb_plugin_is_configurable (RBPlugin *plugin)
{
@@ -180,6 +216,16 @@ rb_plugin_is_configurable (RBPlugin *plugin)
return RB_PLUGIN_GET_CLASS (plugin)->is_configurable (plugin);
}
+/**
+ * rb_plugin_create_configure_dialog:
+ * @plugin: the #RBPlugin
+ *
+ * Creates a configuration dialog for @plugin. The plugin can store
+ * the dialog instance the first time it is created and just return it
+ * thereafter.
+ *
+ * Return value: configuration widget for @plugin
+ */
GtkWidget *
rb_plugin_create_configure_dialog (RBPlugin *plugin)
{
@@ -193,6 +239,13 @@ rb_plugin_create_configure_dialog (RBPlugin *plugin)
#define UNINSTALLED_PLUGINS_LOCATION "plugins"
+/**
+ * rb_get_plugin_paths:
+ *
+ * Returns a list containing the paths to search for plugins.
+ *
+ * Return value: #GList of paths, must be freed by caller
+ */
GList *
rb_get_plugin_paths (void)
{
@@ -225,7 +278,16 @@ rb_get_plugin_paths (void)
return paths;
}
-
+/**
+ * rb_plugin_find_file:
+ * @plugin: the #RBPlugin
+ * @file: file to search for
+ *
+ * Searches for @file in the install directory for @plugin.
+ * Plugins should use this to locate any data files they install.
+ *
+ * Return value: path to the file, must be freed by caller.
+ */
char *
rb_plugin_find_file (RBPlugin *plugin,
const char *file)
@@ -276,3 +338,60 @@ rb_plugin_find_file (RBPlugin *plugin,
}
return ret;
}
+
+/**
+ * RB_PLUGIN_REGISTER:
+ * @PluginName: plugin name in CamelCase
+ * @plugin_name: plugin name in lowercase with words separated by '_'
+ *
+ * Registers a Rhythmbox plugin type. Use this instead of G_DEFINE_TYPE
+ * (or similar) for RBPlugin implementations.
+ */
+
+/**
+ * RB_PLUGIN_REGISTER_TYPE:
+ * @type_name: CamelCase name of the type to register
+ *
+ * Registers additional types for the plugin. This should be called in
+ * the plugin class_init function for types besides the plugin itself that
+ * need to be registered with the GObject type system.
+ */
+
+/**
+ * RB_PLUGIN_DEFINE_TYPE:
+ * @TypeName: type name in CamelCase
+ * @type_name: type name in lowercase with words separated by '_'
+ * @TYPE_PARENT: GType macro for the parent type
+ *
+ * Defines additional types for the plugin. This should be used instead
+ * of G_DEFINE_TYPE for additional object types that need to be registered
+ * with the GObject type system.
+ */
+
+/**
+ * RBPluginActivationFunc:
+ * @plugin: the #RBPlugin
+ * @shell: the #RBShell
+ *
+ * Typedef for plugin activation and deactivation functions.
+ * These functions include the #RBShell as an argument to allow
+ * the plugin to locate other parts of Rhythmbox.
+ */
+
+/**
+ * RBPluginWidgetFunc:
+ * @plugin: the #RBPlugin
+ *
+ * Typedef for plugin configuration functions.
+ *
+ * Return value: a #GtkWidget for the plugin
+ */
+
+/**
+ * RBPluginBooleanFunc
+ * @plugin: the #RBPlugin
+ *
+ * Typedef for plugin functions that return a gboolean.
+ *
+ * Return value: something
+ */
diff --git a/shell/rb-plugin.h b/shell/rb-plugin.h
index b173732..21adfd4 100644
--- a/shell/rb-plugin.h
+++ b/shell/rb-plugin.h
@@ -50,10 +50,14 @@ G_BEGIN_DECLS
/*
* Main object structure
*/
-typedef struct
+
+typedef struct _RBPlugin RBPlugin;
+typedef struct _RBPluginClass RBPluginClass;
+
+struct _RBPlugin
{
GObject parent;
-} RBPlugin;
+};
typedef void (*RBPluginActivationFunc) (RBPlugin *plugin, RBShell *shell);
typedef GtkWidget * (*RBPluginWidgetFunc) (RBPlugin *plugin);
@@ -62,7 +66,7 @@ typedef gboolean (*RBPluginBooleanFunc) (RBPlugin *plugin);
/*
* Class definition
*/
-typedef struct
+struct _RBPluginClass
{
GObjectClass parent_class;
@@ -75,7 +79,7 @@ typedef struct
/* Plugins should not override this, it's handled automatically by
the RbPluginClass */
RBPluginBooleanFunc is_configurable;
-} RBPluginClass;
+};
/*
* Public methods
@@ -99,7 +103,7 @@ GList * rb_get_plugin_paths (void);
/*
* Utility macro used to register plugins
*
- * use: RBT_PLUGIN_REGISTER(RBSamplePlugin, rb_sample_plugin)
+ * use: RB_PLUGIN_REGISTER(RBSamplePlugin, rb_sample_plugin)
*/
#define RB_PLUGIN_REGISTER(PluginName, plugin_name) \
diff --git a/shell/rb-shell.c b/shell/rb-shell.c
index 46f4c2e..6774774 100644
--- a/shell/rb-shell.c
+++ b/shell/rb-shell.c
@@ -710,6 +710,14 @@ rb_shell_class_init (RBShellClass *klass)
RB_TYPE_SOURCE_HEADER,
G_PARAM_READABLE));
+ /**
+ * RBShell::visibility-changed:
+ * @shell: the #RBShell
+ * @visibile: new visibility
+ *
+ * Emitted after the visibility of the main Rhythmbox window has
+ * changed.
+ */
rb_shell_signals[VISIBILITY_CHANGED] =
g_signal_new ("visibility_changed",
G_OBJECT_CLASS_TYPE (object_class),
@@ -720,6 +728,16 @@ rb_shell_class_init (RBShellClass *klass)
G_TYPE_NONE,
1,
G_TYPE_BOOLEAN);
+ /**
+ * RBShell::visibility-changing:
+ * @shell: the #RBShell
+ * @initial: if %TRUE, this is the initial visibility for the window
+ * @visible: new shell visibility
+ *
+ * Emitted before the visibility of the main window changes. The return
+ * value overrides the visibility setting. If multiple signal handlers
+ * are attached, the last one wins.
+ */
rb_shell_signals[VISIBILITY_CHANGING] =
g_signal_new ("visibility_changing",
G_OBJECT_CLASS_TYPE (object_class),
@@ -732,6 +750,16 @@ rb_shell_class_init (RBShellClass *klass)
G_TYPE_BOOLEAN,
G_TYPE_BOOLEAN);
+ /**
+ * RBShell::create-song-info:
+ * @shell: the #RBShell
+ * @song_info: the new #RBSongInfo window
+ * @multi: if %TRUE, the song info window is for multiple entries
+ *
+ * Emitted when creating a new #RBSongInfo window. Signal handlers can
+ * add pages to the song info window notebook to display additional
+ * information.
+ */
rb_shell_signals[CREATE_SONG_INFO] =
g_signal_new ("create_song_info",
G_OBJECT_CLASS_TYPE (object_class),
@@ -742,6 +770,17 @@ rb_shell_class_init (RBShellClass *klass)
G_TYPE_NONE,
2,
RB_TYPE_SONG_INFO, G_TYPE_BOOLEAN);
+ /**
+ * RBShell::removable-media-scan-finished:
+ * @shell: the #RBShell
+ *
+ * Emitted when the initial scan for removable media devices is
+ * complete. This is intended to allow plugins to request a
+ * device scan only if the scan on startup has already been done,
+ * but it isn't very useful for that.
+ * See #RBRemovableMediaManager:scanned for a better approach to
+ * this problem.
+ */
rb_shell_signals[REMOVABLE_MEDIA_SCAN_FINISHED] =
g_signal_new ("removable_media_scan_finished",
G_OBJECT_CLASS_TYPE (object_class),
@@ -751,6 +790,13 @@ rb_shell_class_init (RBShellClass *klass)
g_cclosure_marshal_VOID__VOID,
G_TYPE_NONE,
0);
+ /**
+ * RBShell::notify-playing-entry:
+ * @shell: the #RBShell
+ *
+ * Emitted when a notification should be displayed showing the current
+ * playing entry.
+ */
rb_shell_signals[NOTIFY_PLAYING_ENTRY] =
g_signal_new ("notify-playing-entry",
G_OBJECT_CLASS_TYPE (object_class),
@@ -761,6 +807,17 @@ rb_shell_class_init (RBShellClass *klass)
G_TYPE_NONE,
1,
G_TYPE_BOOLEAN);
+ /**
+ * RBShell::notify-custom:
+ * @shell: the #RBShell
+ * @timeout: length of time (in seconds) to display the notification
+ * @primary: main notification text
+ * @secondary: secondary notification text
+ * @pixbuf: an image to include in the notification (optional)
+ * @requested: if %TRUE, the notification was triggered by an explicit user action
+ *
+ * Emitted when a custom notification should be displayed to the user.
+ */
rb_shell_signals[NOTIFY_CUSTOM] =
g_signal_new ("notify-custom",
G_OBJECT_CLASS_TYPE (object_class),
@@ -2956,7 +3013,9 @@ rb_shell_do_notify (RBShell *shell, gboolean requested, GError **error)
/**
* rb_shell_error_quark:
*
- * Return value: the #GQuark used for #RBShell errors
+ * Returns the #GQuark used for #RBShell errors
+ *
+ * Return value: shell error #GQuark
*/
GQuark
rb_shell_error_quark (void)
diff --git a/shell/rb-source-header.c b/shell/rb-source-header.c
index 53fafa0..7f4d3d1 100644
--- a/shell/rb-source-header.c
+++ b/shell/rb-source-header.c
@@ -248,6 +248,13 @@ rb_source_header_class_init (RBSourceHeaderClass *klass)
GTK_TYPE_UI_MANAGER,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
+ /**
+ * RBSourceHeader::get-search-actions:
+ * @header: the #RBSourceHeader
+ *
+ * Allows signal handlers to add search actions to the search
+ * bar by returning an array of search action names.
+ */
rb_source_header_signals[GET_SEARCH_ACTIONS] =
g_signal_new ("get-search-actions",
G_OBJECT_CLASS_TYPE (object_class),
@@ -259,6 +266,15 @@ rb_source_header_class_init (RBSourceHeaderClass *klass)
1,
RB_TYPE_SOURCE);
+ /**
+ * RBSourceHeader::refresh-search-bar:
+ * @header: the #RBSourceHeader
+ *
+ * An action signal used to repopulate the search bar.
+ * This should be called after a signal handler for
+ * #::get-search-actions has been connected
+ * or disconnected.
+ */
rb_source_header_signals[REFRESH_SEARCH_BAR] =
g_signal_new ("refresh-search-bar",
G_OBJECT_CLASS_TYPE (object_class),
diff --git a/sources/rb-removable-media-source.c b/sources/rb-removable-media-source.c
index 4154361..3cf1f7f 100644
--- a/sources/rb-removable-media-source.c
+++ b/sources/rb-removable-media-source.c
@@ -724,7 +724,7 @@ rb_removable_media_source_get_format_descriptions (RBRemovableMediaSource *sourc
}
/**
- * rb_removablem_media_source_should_paste_no_duplicate:
+ * rb_removable_media_source_should_paste_no_duplicate:
* @source: an #RBRemovableMediaSource
* @entry: a #RhythmDBEntry to consider pasting
*
diff --git a/sources/rb-source-group.c b/sources/rb-source-group.c
index abbe707..c18296e 100644
--- a/sources/rb-source-group.c
+++ b/sources/rb-source-group.c
@@ -191,7 +191,9 @@ rb_source_group_register (const char *name,
/**
* rb_source_group_library_get_type:
*
- * Return value: the predefined library source group
+ * Returns the predefined library source group
+ *
+ * Return value: library source group
*/
RBSourceGroup *
rb_source_group_library_get_type (void)
diff --git a/sources/rb-source.c b/sources/rb-source.c
index 5cc3c89..a3f8187 100644
--- a/sources/rb-source.c
+++ b/sources/rb-source.c
@@ -384,7 +384,7 @@ rb_source_class_init (RBSourceClass *klass)
0);
/**
- * RBSource::status_changed:
+ * RBSource::status-changed:
* @source: the #RBSource
*
* Emitted when the source's status changes.
@@ -400,7 +400,7 @@ rb_source_class_init (RBSourceClass *klass)
0);
/**
- * RBSource::filter_changed:
+ * RBSource::filter-changed:
* @source: the #RBSource
*
* Fires when the user changes the filter, either by changing the
diff --git a/sources/rb-sourcelist.c b/sources/rb-sourcelist.c
index cc4fc5d..3a6b0f3 100644
--- a/sources/rb-sourcelist.c
+++ b/sources/rb-sourcelist.c
@@ -844,6 +844,8 @@ rb_sourcelist_get_property (GObject *object,
* rb_sourcelist_new:
* @shell: the #RBShell instance
*
+ * Creates the source list widget.
+ *
* Return value: the source list widget.
*/
GtkWidget *
diff --git a/widgets/rb-rating.c b/widgets/rb-rating.c
index 4fadcf7..391a142 100644
--- a/widgets/rb-rating.c
+++ b/widgets/rb-rating.c
@@ -147,6 +147,13 @@ rb_rating_class_init (RBRatingClass *klass)
G_TYPE_NONE,
1,
G_TYPE_DOUBLE);
+ /**
+ * RBRating::set-rating:
+ * @rating: the #RBRating
+ * @score: the new rating
+ *
+ * Action signal used to change the rating.
+ */
rb_rating_signals[SET_RATING] =
g_signal_new ("set-rating",
G_OBJECT_CLASS_TYPE (object_class),
@@ -157,6 +164,14 @@ rb_rating_class_init (RBRatingClass *klass)
G_TYPE_NONE,
1,
G_TYPE_DOUBLE);
+ /**
+ * RBRating::adjust-rating:
+ * @rating: the #RBRating
+ * @adjust: value to add to the rating
+ *
+ * Action signal used to make a relative adjustment to the
+ * rating.
+ */
rb_rating_signals[ADJUST_RATING] =
g_signal_new ("adjust-rating",
G_OBJECT_CLASS_TYPE (object_class),
diff --git a/widgets/rb-search-entry.c b/widgets/rb-search-entry.c
index 527abc0..71b1200 100644
--- a/widgets/rb-search-entry.c
+++ b/widgets/rb-search-entry.c
@@ -207,6 +207,8 @@ rb_search_entry_finalize (GObject *object)
/**
* rb_search_entry_new:
*
+ * Creates a new search entry widget.
+ *
* Return value: new search entry widget.
*/
RBSearchEntry *
@@ -340,7 +342,9 @@ rb_search_entry_focus_out_event_cb (GtkWidget *widget,
* rb_search_entry_searching:
* @entry: a #RBSearchEntry
*
- * Return value: TRUE if there is search text
+ * Returns %TRUE if there is search text in the entry widget.
+ *
+ * Return value: %TRUE if searching
*/
gboolean
rb_search_entry_searching (RBSearchEntry *entry)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
