Add doc-comments for Stash setting functions.

Add an example file showing usage of Stash.
(Not enabled yet until added to the plugin API).



git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@4769 ea778897-0a13-0410-b9d1-a72fbfd435f5

ChangeLog

@@ -3,6 +3,11 @@
  * tagmanager/python.c:
    Apply patch from Colomban Wendling to parse Python lambda functions
    (thanks) - modified to only parse toplevel or class member lambdas.
+ * src/stash.c, src/stash.h, doc/Doxyfile.in, doc/Makefile.am,
+   doc/stash-example.c:
+   Add doc-comments for Stash setting functions.
+   Add an example file showing usage of Stash.
+   (Not enabled yet until added to the plugin API).
 
 
 2010-03-17  Lex Trotman  <elextr.at.gmail.dot.com>

doc/Doxyfile.in

@@ -124,7 +124,7 @@ EXCLUDE                =
 EXCLUDE_SYMLINKS       = NO
 EXCLUDE_PATTERNS       =
 EXCLUDE_SYMBOLS        =
-EXAMPLE_PATH           =
+EXAMPLE_PATH           = .
 EXAMPLE_PATTERNS       = *
 EXAMPLE_RECURSIVE      = NO
 IMAGE_PATH             =

doc/Makefile.am

@@ -2,6 +2,7 @@ man_MANS=geany.1
 DOCDIR = $(DESTDIR)$(docdir)
 IMAGE_FILES = images/*.png
 EXTRA_DIST = geany.html geany.css geany.txt geany.1 plugins.dox pluginsymbols.c \
+			 stash-example.c \
 			 $(srcdir)/$(IMAGE_FILES)
 
 pdf: geany.txt

doc/stash-example.c

@@ -0,0 +1,33 @@
+GeanyPrefGroup *group;
+gboolean china_enabled;
+gchar *potter_name = NULL; /* strings must be initialised */
+GKeyFile *keyfile;
+const gchar filename[] = "/path/to/data.conf";
+gchar *data;
+
+/* setup the group */
+group = stash_group_new("cups");
+stash_group_add_boolean(group, &china_enabled, "china", TRUE);
+stash_group_add_string(group, &potter_name, "potter_name", "Miss Clay");
+
+/* load the settings from a file */
+keyfile = g_key_file_new();
+g_key_file_load_from_file(keyfile, filename, G_KEY_FILE_NONE, NULL);
+stash_group_load_from_key_file(group, keyfile);
+g_key_file_free(keyfile);
+
+/* now use settings china_enabled and potter_name */
+...
+
+/* save settings to file */
+keyfile = g_key_file_new();
+stash_group_save_to_key_file(group, keyfile);
+data = g_key_file_to_data(keyfile, NULL, NULL);
+if (utils_write_file(filename, data) != 0)
+	dialogs_show_msgbox(GTK_MESSAGE_ERROR,
+		_("Could not save keyfile %s!"), filename);
+g_free(data);
+g_key_file_free(keyfile);
+
+/* free memory */
+stash_group_free(group);

src/stash.c

@@ -22,27 +22,38 @@
  * $Id$
  */
 
-/* Mini-library for reading/writing GKeyFile settings and synchronizing widgets with
- * C variables. */
-
-/* Terms
+/*
+ * @file stash.h
+ * Lightweight library for reading/writing @c GKeyFile settings and synchronizing widgets with
+ * C variables.
+ *
+ * Note: Stash should only depend on GLib and GTK, but currently has some minor
+ * dependencies on Geany's utils.c.
+ *
+ * @section Terms
  * 'Setting' is used only for data stored on disk or in memory.
  * 'Pref' can also include visual widget information.
  *
- * Memory Usage
+ * @section Memory Usage
  * Stash will not duplicate strings if they are normally static arrays, such as
  * keyfile group names and key names, string default values, widget_id names, property names.
  *
- * String Settings
+ * @section String Settings
  * String settings and other dynamically allocated settings must be initialized to NULL as they
  * will be freed before reassigning.
  *
- * Widget Support
+ * @section Widget Support
  * Widgets very commonly used in configuration dialogs will be supported with their own function.
  * Widgets less commonly used such as GtkExpander or widget settings that aren't commonly needed
  * to be persistent won't be directly supported, to keep the library lightweight. However, you can
  * use stash_group_add_widget_property() to also save these settings for any read/write widget
  * property.
+ *
+ * @section Example
+ * @include stash-example.c
+ */
+/* TODO: Type naming should be changed to be independent of Geany.
+ * TODO: Rename to GStash as a libstash already exists.
  */
 
 /* Implementation Note
@@ -56,7 +67,9 @@
  * Usually the prefs code isn't what user code will spend most of its time doing, so this
  * should be efficient enough. But, if desired we could add a stash_group_set_size() function
  * to reduce reallocation.
- * */
+ *
+ * TODO: Maybe using GSlice chunks with an extra 'next' pointer would be more (memory) efficient.
+ */
 
 
 #include <gtk/gtk.h>
@@ -76,6 +89,8 @@ struct GeanyPrefEntry
 	gpointer fields;			/* extra fields */
 };
 
+typedef struct GeanyPrefEntry GeanyPrefEntry;
+
 struct GeanyPrefGroup
 {
 	const gchar *name;			/* group name to use in the keyfile */
@@ -227,18 +242,27 @@ static void keyfile_action(SettingAction action, GeanyPrefGroup *group, GKeyFile
 }
 
 
+/** Reads all key values (usually from a configuration file) into the group settings.
+ * @param group .
+ * @param keyfile . */
 void stash_group_load_from_key_file(GeanyPrefGroup *group, GKeyFile *keyfile)
 {
 	keyfile_action(SETTING_READ, group, keyfile);
 }
 
 
+/** Writes group settings into key values for a configuration file.
+ * @param group .
+ * @param keyfile . */
 void stash_group_save_to_key_file(GeanyPrefGroup *group, GKeyFile *keyfile)
 {
 	keyfile_action(SETTING_WRITE, group, keyfile);
 }
 
 
+/** Creates a new group.
+ * @param name Name used for @c GKeyFile group.
+ * @return Group. */
 GeanyPrefGroup *stash_group_new(const gchar *name)
 {
 	GeanyPrefGroup *group = g_new0(GeanyPrefGroup, 1);
@@ -250,6 +274,8 @@ GeanyPrefGroup *stash_group_new(const gchar *name)
 }
 
 
+/** Frees a group.
+ * @param group . */
 void stash_group_free(GeanyPrefGroup *group)
 {
 	GeanyPrefEntry *entry;
@@ -299,6 +325,11 @@ add_pref(GeanyPrefGroup *group, GType type, gpointer setting,
 }
 
 
+/** Adds boolean setting.
+ * @param group .
+ * @param setting Address of setting variable.
+ * @param key_name Name for key in a @c GKeyFile.
+ * @param default_value Value to use if the key doesn't exist when loading. */
 void stash_group_add_boolean(GeanyPrefGroup *group, gboolean *setting,
 		const gchar *key_name, gboolean default_value)
 {
@@ -306,6 +337,11 @@ void stash_group_add_boolean(GeanyPrefGroup *group, gboolean *setting,
 }
 
 
+/** Adds integer setting.
+ * @param group .
+ * @param setting Address of setting variable.
+ * @param key_name Name for key in a @c GKeyFile.
+ * @param default_value Value to use if the key doesn't exist when loading. */
 void stash_group_add_integer(GeanyPrefGroup *group, gint *setting,
 		const gchar *key_name, gint default_value)
 {
@@ -313,9 +349,13 @@ void stash_group_add_integer(GeanyPrefGroup *group, gint *setting,
 }
 
 
-/* The contents of @a setting will be freed before being replaced, so make sure it is
+/** Adds string setting.
+ * The contents of @a setting will be freed before being replaced, so make sure it is
  * allocated, or initialized to @c NULL.
- * @param default_value Not duplicated. */
+ * @param group .
+ * @param setting Address of setting variable.
+ * @param key_name Name for key in a @c GKeyFile.
+ * @param default_value Value to use if the key doesn't exist when loading. Not duplicated. */
 void stash_group_add_string(GeanyPrefGroup *group, gchar **setting,
 		const gchar *key_name, const gchar *default_value)
 {
@@ -323,9 +363,13 @@ void stash_group_add_string(GeanyPrefGroup *group, gchar **setting,
 }
 
 
-/* The contents of @a setting will be freed before being replaced, so make sure it is
+/** Adds string vector setting (array of strings).
+ * The contents of @a setting will be freed before being replaced, so make sure it is
  * allocated, or initialized to @c NULL.
- * @param default_value Not duplicated. */
+ * @param group .
+ * @param setting Address of setting variable.
+ * @param key_name Name for key in a @c GKeyFile.
+ * @param default_value Value to use if the key doesn't exist when loading. Not duplicated. */
 void stash_group_add_string_vector(GeanyPrefGroup *group, gchar ***setting,
 		const gchar *key_name, const gchar **default_value)
 {
@@ -572,7 +616,7 @@ static void pref_action(PrefAction action, GeanyPrefGroup *group, GtkWidget *own
 }
 
 
-/** @param owner If non-NULL, used to lookup widgets by name. */
+/* @param owner If non-NULL, used to lookup widgets by name. */
 void stash_group_display(GeanyPrefGroup *group, GtkWidget *owner)
 {
 	pref_action(PREF_DISPLAY, group, owner);

src/stash.h

@@ -25,12 +25,11 @@
 #ifndef GEANY_STASH_H
 #define GEANY_STASH_H
 
-typedef struct GeanyPrefEntry GeanyPrefEntry;
-
+/** Opaque type for a group of settings. */
 typedef struct GeanyPrefGroup GeanyPrefGroup;
 
-/* Can be (GtkWidget*) or (gchar*) depending on whether owner argument is used for
- * stash_group_display/stash_group_update. */
+/* Can be @c GtkWidget* or @c gchar* depending on whether the @c owner argument is used for
+ * stash_group_display() and stash_group_update(). */
 typedef gpointer GeanyWidgetID;