X-Git-Url: http://pileus.org/git/?a=blobdiff_plain;f=src%2Fgis-prefs.c;h=2eb5b4d4891595ff4d323bebffd72111a1247cc0;hb=b74c9331acec6b524692191f3fd8c0075aeb814f;hp=70b5006e59a6f01fd8bcbb9f05439f50744de177;hpb=bd716715f1d13a8df514fcfa53fd82aebdfda770;p=grits

diff --git a/src/gis-prefs.c b/src/gis-prefs.c
index 70b5006..2eb5b4d 100644
--- a/src/gis-prefs.c
+++ b/src/gis-prefs.c
@@ -15,6 +15,21 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:gis-prefs
+ * @short_description: Persistent preference handing
+ *
+ * #GisPrefs is used to store and access preferences in libgis. It is mostly a
+ * wrapper around a #GKeyFile. Preferences can be stored for the application
+ * using libgis, but may also be stored by libgis itself. An example of this are
+ * whether libgis is in online or offline mode. Many #GisPlugin<!-- -->s also
+ * store preferences.
+ *
+ * There are two variants of preference functions. The normal variant takes
+ * group and a key separated by a "/" as they key to the preference. The "_v"
+ * variant takes the group and the key as separate parameters.
+ */
+
 #include <config.h>
 
 #include <glib.h>
@@ -30,6 +45,16 @@ static guint signals[NUM_SIGNALS];
 /***********
  * Methods *
  ***********/
+/**
+ * gis_prefs_new:
+ * @config:   the path to the config file
+ * @defaults: the path to the default config file
+ *
+ * Create a new preference object for the given @config. If the config does not
+ * exist the @defaults file is loaded.
+ *
+ * Returns: the new #GisPrefs
+ */
 GisPrefs *gis_prefs_new(const gchar *config, const gchar *defaults)
 {
 	g_debug("GisPrefs: new - %s, %s", config, defaults);
@@ -65,11 +90,11 @@ GisPrefs *gis_prefs_new(const gchar *config, const gchar *defaults)
 }
 
 #define make_pref_type(name, c_type, g_type)                                         \
-c_type gis_prefs_get_##name##_v(GisPrefs *prefs,                                      \
+c_type gis_prefs_get_##name##_v(GisPrefs *prefs,                                     \
 		const gchar *group, const gchar *key, GError **_error)               \
 {                                                                                    \
 	GError *error = NULL;                                                        \
-	c_type value = g_key_file_get_##name(prefs->key_file, group, key, &error);    \
+	c_type value = g_key_file_get_##name(prefs->key_file, group, key, &error);   \
 	if (error && error->code != G_KEY_FILE_ERROR_GROUP_NOT_FOUND)                \
 		g_warning("GisPrefs: get_value_##name - error getting key %s: %s\n", \
 				key, error->message);                                \
@@ -77,27 +102,27 @@ c_type gis_prefs_get_##name##_v(GisPrefs *prefs,
 		*_error = error;                                                     \
 	return value;                                                                \
 }                                                                                    \
-c_type gis_prefs_get_##name(GisPrefs *prefs, const gchar *key, GError **error)        \
+c_type gis_prefs_get_##name(GisPrefs *prefs, const gchar *key, GError **error)       \
 {                                                                                    \
 	gchar **keys  = g_strsplit(key, "/", 2);                                     \
-	c_type value = gis_prefs_get_##name##_v(prefs, keys[0], keys[1], error);      \
+	c_type value = gis_prefs_get_##name##_v(prefs, keys[0], keys[1], error);     \
 	g_strfreev(keys);                                                            \
 	return value;                                                                \
 }                                                                                    \
                                                                                      \
-void gis_prefs_set_##name##_v(GisPrefs *prefs,                                        \
+void gis_prefs_set_##name##_v(GisPrefs *prefs,                                       \
 		const gchar *group, const gchar *key, const c_type value)            \
 {                                                                                    \
-	g_key_file_set_##name(prefs->key_file, group, key, value);                    \
+	g_key_file_set_##name(prefs->key_file, group, key, value);                   \
 	gchar *all = g_strconcat(group, "/", key, NULL);                             \
-	g_signal_emit(prefs, signals[SIG_PREF_CHANGED], 0,                            \
+	g_signal_emit(prefs, signals[SIG_PREF_CHANGED], 0,                           \
 			all, g_type, &value);                                        \
 	g_free(all);                                                                 \
 }                                                                                    \
-void gis_prefs_set_##name(GisPrefs *prefs, const gchar *key, const c_type value)      \
+void gis_prefs_set_##name(GisPrefs *prefs, const gchar *key, const c_type value)     \
 {                                                                                    \
 	gchar **keys = g_strsplit(key, "/", 2);                                      \
-	gis_prefs_set_##name##_v(prefs, keys[0], keys[1], value);                     \
+	gis_prefs_set_##name##_v(prefs, keys[0], keys[1], value);                    \
 	g_strfreev(keys);                                                            \
 }                                                                                    \
 
@@ -138,7 +163,18 @@ static void gis_prefs_class_init(GisPrefsClass *klass)
 {
 	g_debug("GisPrefs: class_init");
 	GObjectClass *gobject_class = G_OBJECT_CLASS(klass);
-	gobject_class->dispose      = gis_prefs_dispose;
+	gobject_class->dispose = gis_prefs_dispose;
+
+	/**
+	 * GisPrefs::pref-changed:
+	 * @prefs: the preference store.
+	 * @key:   the key to the preference.
+	 * @type:  the type of the preference that changed.
+	 * @value: a pointer to the value of the preference.
+	 *
+	 * The ::pref-changed signal is emitted each time a preference is
+	 * changed.
+	 */
 	signals[SIG_PREF_CHANGED] = g_signal_new(
 			"pref-changed",
 			G_TYPE_FROM_CLASS(gobject_class),
@@ -148,7 +184,7 @@ static void gis_prefs_class_init(GisPrefsClass *klass)
 			NULL,
 			gis_cclosure_marshal_VOID__STRING_UINT_POINTER,
 			G_TYPE_NONE,
-			1,
+			3,
 			G_TYPE_STRING,
 			G_TYPE_UINT,
 			G_TYPE_POINTER);