rhythmbox r5659 - in trunk: . doc/reference lib

[jmatthew svn gnome org]

Author: jmatthew
Date: Sun Mar 30 22:37:43 2008
New Revision: 5659
URL: http://svn.gnome.org/viewvc/rhythmbox?rev=5659&view=rev

Log:
2008-03-31  Jonathan Matthew  <jonathan d14n org>

	* doc/reference/rhythmbox-sections.txt:
	* lib/rb-proxy-config.c: (rb_proxy_config_class_init):
	* lib/rb-proxy-config.h:
	* lib/rb-string-value-map.c:
	* lib/rb-string-value-map.h:
	Add gtk-doc for RBProxyConfig and RBStringValueMap.


Modified:
   trunk/ChangeLog
   trunk/doc/reference/rhythmbox-sections.txt
   trunk/lib/rb-proxy-config.c
   trunk/lib/rb-proxy-config.h
   trunk/lib/rb-string-value-map.c
   trunk/lib/rb-string-value-map.h

Modified: trunk/doc/reference/rhythmbox-sections.txt
==============================================================================
--- trunk/doc/reference/rhythmbox-sections.txt	(original)
+++ trunk/doc/reference/rhythmbox-sections.txt	Sun Mar 30 22:37:43 2008
@@ -2202,7 +2202,9 @@
 
 <SECTION>
 <FILE>rb-string-value-map</FILE>
-RBStringValueMapPrivate
+<TITLE>RBStringValueMap</TITLE>
+RBStringValueMap
+RBStringValueMapClass
 rb_string_value_map_new
 rb_string_value_map_set
 rb_string_value_map_get
@@ -2217,12 +2219,14 @@
 rb_string_value_map_get_type
 RB_STRING_VALUE_MAP_CLASS
 RB_IS_STRING_VALUE_MAP_CLASS
+RBStringValueMapPrivate
 </SECTION>
 
 <SECTION>
 <FILE>rb-proxy-config</FILE>
-RBProxyConfigPrivate
-config_changed
+<TITLE>RBProxyConfig</TITLE>
+RBProxyConfig
+RBProxyConfigClass
 rb_proxy_config_new
 rb_proxy_config_get_libsoup_uri
 <SUBSECTION Standard>
@@ -2233,6 +2237,7 @@
 RB_PROXY_CONFIG_CLASS
 RB_IS_PROXY_CONFIG_CLASS
 RB_PROXY_CONFIG_GET_CLASS
+RBProxyConfigPrivate
 </SECTION>
 
 <SECTION>

Modified: trunk/lib/rb-proxy-config.c
==============================================================================
--- trunk/lib/rb-proxy-config.c	(original)
+++ trunk/lib/rb-proxy-config.c	Sun Mar 30 22:37:43 2008
@@ -29,6 +29,16 @@
 #include "rb-debug.h"
 #include "rb-dialog.h"
 
+/**
+ * SECTION:rb-proxy-config
+ * @short_description: GConf HTTP proxy retriever
+ *
+ * This class knows how to retrieve the current HTTP proxy configuration
+ * from GConf, and also emits signals when the configuration is changed.
+ * It only supports manual proxy configuration (with authentication).  It
+ * does not support any of the various automatic proxy configuration schemes.
+ */
+
 enum
 {
 	CONFIG_CHANGED,
@@ -69,6 +79,12 @@
 	object_class->dispose = rb_proxy_config_dispose;
 	object_class->finalize = rb_proxy_config_finalize;
 
+	/**
+	 * RBProxyConfig::config-changed:
+	 * @config: the #RBProxyConfig
+	 *
+	 * Emitted when the HTTP proxy configuration is changed.
+	 */
 	rb_proxy_config_signals [CONFIG_CHANGED] =
 		g_signal_new ("config-changed",
 			      G_OBJECT_CLASS_TYPE (object_class),
@@ -159,6 +175,11 @@
 	G_OBJECT_CLASS (rb_proxy_config_parent_class)->finalize (object);
 }
 
+/**
+ * rb_proxy_config_new:
+ *
+ * Return value: new proxy configuration retriever
+ */
 RBProxyConfig *
 rb_proxy_config_new ()
 {
@@ -231,6 +252,12 @@
 	}
 }
 
+/**
+ * rb_proxy_config_get_libsoup_uri:
+ * @config: a #RBProxyConfig
+ *
+ * Return value: a libsoup URI object containing the current HTTP proxy configuration.
+ */
 #if defined(HAVE_LIBSOUP_2_4)
 SoupURI *
 rb_proxy_config_get_libsoup_uri (RBProxyConfig *config)

Modified: trunk/lib/rb-proxy-config.h
==============================================================================
--- trunk/lib/rb-proxy-config.h	(original)
+++ trunk/lib/rb-proxy-config.h	Sun Mar 30 22:37:43 2008
@@ -37,9 +37,11 @@
 #define RB_IS_PROXY_CONFIG_CLASS(k)		(G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_PROXY_CONFIG))
 #define RB_PROXY_CONFIG_GET_CLASS(o)		(G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_PROXY_CONFIG, RBProxyConfigClass))
 
+typedef struct _RBProxyConfig RBProxyConfig;
+typedef struct _RBProxyConfigClass RBProxyConfigClass;
 typedef struct _RBProxyConfigPrivate RBProxyConfigPrivate;
 
-typedef struct
+struct _RBProxyConfig
 {
 	GObject parent;
 	gboolean enabled;
@@ -51,14 +53,14 @@
 	char *password;
 
 	RBProxyConfigPrivate *priv;
-} RBProxyConfig;
+};
 
-typedef struct
+struct _RBProxyConfigClass
 {
 	GObjectClass parent_class;
 
 	void (*config_changed) (RBProxyConfig *config);
-} RBProxyConfigClass;
+};
 
 
 GType		rb_proxy_config_get_type (void);

Modified: trunk/lib/rb-string-value-map.c
==============================================================================
--- trunk/lib/rb-string-value-map.c	(original)
+++ trunk/lib/rb-string-value-map.c	Sun Mar 30 22:37:43 2008
@@ -23,6 +23,15 @@
 
 #include "rb-util.h"
 
+/**
+ * SECTION:rb-string-value-map
+ * @short_description: specialized hash table for storing string to GValue mappings
+ *
+ * Simplifies the use of string:GValue maps with respect to copying of the values
+ * inserted into the map.  Except for rb_string_value_map_peek, the caller retains
+ * ownership of values passed in, and assumes ownership of all values returned.
+ */
+
 static void rb_string_value_map_finalize (GObject *obj);
 
 
@@ -64,6 +73,11 @@
 	G_OBJECT_CLASS(rb_string_value_map_parent_class)->finalize (obj);
 }
 
+/**
+ * rb_string_value_map_new:
+ *
+ * Return value: new empty #RBStringValueMap
+ */
 RBStringValueMap*
 rb_string_value_map_new (void)
 {
@@ -71,6 +85,14 @@
 }
 
 
+/**
+ * rb_string_value_map_set:
+ * @map: a #RBStringValueMap
+ * @key: key to set
+ * @value: value to store
+ *
+ * Inserts a value into the map.  The value is copied.
+ */
 void
 rb_string_value_map_set (RBStringValueMap *map,
 			 const char *key,
@@ -84,6 +106,15 @@
 	g_hash_table_insert (map->priv->map, g_strdup(key), val);
 }
 
+/**
+ * rb_string_value_map_remove:
+ * @map: a #RBStringValueMap
+ * @key: key to remove
+ *
+ * Removes a value from the map.
+ *
+ * Return value: %TRUE if the value was found and removed
+ */
 gboolean
 rb_string_value_map_remove (RBStringValueMap *map,
 			    const char *key)
@@ -91,12 +122,28 @@
 	return g_hash_table_remove (map->priv->map, key);
 }
 
+/**
+ * rb_string_value_map_size:
+ * @map: a #RBStringValueMap
+ *
+ * Return value: the number of entries in the map
+ */
 guint
 rb_string_value_map_size (RBStringValueMap *map)
 {
 	return g_hash_table_size (map->priv->map);
 }
 
+/**
+ * rb_string_value_map_get:
+ * @map: a #RBStringValueMap
+ * @key: key to retrieve
+ * @out: returns a copy of the value in the map
+ *
+ * Locates and copies the value associated with the key.
+ *
+ * Return value: %TRUE if the value was found
+ */
 gboolean
 rb_string_value_map_get (RBStringValueMap *map,
 			 const char *key,
@@ -114,6 +161,16 @@
 	return TRUE;
 }
 
+/**
+ * rb_string_value_map_peek:
+ * @map: a #RBStringValueMap
+ * @key: key to retrieve
+ *
+ * Locates the value associated with the key.  This returns the
+ * GValue stored in the map, so it cannot be modified.
+ *
+ * Return value: the GValue associated with the key
+ */
 const GValue*
 rb_string_value_map_peek (RBStringValueMap *map,
 			  const char *key)
@@ -121,6 +178,15 @@
 	return g_hash_table_lookup (map->priv->map, key);
 }
 
+/**
+ * rb_string_value_map_steal_hashtable:
+ * @map: a #RBStringValueMap
+ *
+ * Extracts and returns the underlying hash table from the map,
+ * and creates a new empty map.
+ *
+ * Return value: #GHashTable from the map
+ */
 GHashTable*
 rb_string_value_map_steal_hashtable (RBStringValueMap *map)
 {

Modified: trunk/lib/rb-string-value-map.h
==============================================================================
--- trunk/lib/rb-string-value-map.h	(original)
+++ trunk/lib/rb-string-value-map.h	Sun Mar 30 22:37:43 2008
@@ -30,19 +30,22 @@
 #define RB_IS_STRING_VALUE_MAP(obj)         (GTK_CHECK_TYPE ((obj), RB_TYPE_STRING_VALUE_MAP))
 #define RB_IS_STRING_VALUE_MAP_CLASS(klass) (GTK_CHECK_CLASS_TYPE ((klass), RB_TYPE_STRING_VALUE_MAP))
 
+typedef struct _RBStringValueMap RBStringValueMap;
+typedef struct _RBStringValueMapClass RBStringValueMapClass;
+
 typedef struct RBStringValueMapPrivate RBStringValueMapPrivate;
 
-typedef struct
+struct _RBStringValueMap
 {
 	GObject parent;
 
 	RBStringValueMapPrivate *priv;
-} RBStringValueMap;
+};
 
-typedef struct
+struct _RBStringValueMapClass
 {
 	GObjectClass parent;
-} RBStringValueMapClass;
+};
 
 GType    rb_string_value_map_get_type (void);