[seahorse] Bug 585538 – Add GTK-Doc comments
- From: Adam Schreiber <sadam src gnome org>
- To: svn-commits-list gnome org
- Cc:
- Subject: [seahorse] Bug 585538 – Add GTK-Doc comments
- Date: Tue, 11 Aug 2009 17:24:08 +0000 (UTC)
commit d4eb6ecf3578dd6bcff3efe3075d1f06d01979d3
Author: Thorsten Sick <thorsten sick email de>
Date: Tue Aug 11 13:20:04 2009 -0400
Bug 585538 â?? Add GTK-Doc comments
gtk-doc comments
libseahorse/seahorse-gconf.c | 143 +++++++++++++-
libseahorse/seahorse-gtkstock.c | 40 ++++
libseahorse/seahorse-object.c | 366 ++++++++++++++++++++++++++++++++--
libseahorse/seahorse-prefs.c | 16 ++
libseahorse/seahorse-secure-memory.c | 52 +++++
libseahorse/seahorse-util.c | 362 ++++++++++++++++++++++++++++++----
libseahorse/seahorse-validity.c | 6 +
7 files changed, 933 insertions(+), 52 deletions(-)
---
diff --git a/libseahorse/seahorse-gconf.c b/libseahorse/seahorse-gconf.c
index 416ff7b..5a78c5b 100644
--- a/libseahorse/seahorse-gconf.c
+++ b/libseahorse/seahorse-gconf.c
@@ -25,6 +25,12 @@
static GConfClient *global_gconf_client = NULL;
+/**
+ * global_client_free:
+ *
+ * Removes the registered dirs and frees the global gconf client
+ *
+ */
static void
global_client_free (void)
{
@@ -38,6 +44,14 @@ global_client_free (void)
global_gconf_client = NULL;
}
+/**
+ * handle_error:
+ * @error:the error to report
+ *
+ * The error is reported as a warning (#g_warning) and freed afterwards.
+ *
+ * Returns: TRUE if an error has been handled, FALSE else
+ */
static gboolean
handle_error (GError **error)
{
@@ -53,7 +67,15 @@ handle_error (GError **error)
return FALSE;
}
-
+
+/**
+ * get_global_client:
+ *
+ * Initializes the global gconf client if needed. Can be called with a client
+ * already initialized.
+ *
+ * Returns: The global GConfClient
+ */
static GConfClient*
get_global_client (void)
{
@@ -87,12 +109,27 @@ get_global_client (void)
return global_gconf_client;
}
+/**
+ * seahorse_gconf_disconnect:
+ *
+ * Remove registered dirs and free the global gconf client
+ *
+ */
void
seahorse_gconf_disconnect ()
{
global_client_free ();
}
+/**
+ * seahorse_gconf_set_boolean:
+ * @key: The key
+ * @boolean_value: The value to set
+ *
+ * Set a value for a boolean key in the GConf storage
+ *
+ * Errors are handled internally and are mapped to a warning
+ */
void
seahorse_gconf_set_boolean (const char *key, gboolean boolean_value)
{
@@ -108,6 +145,14 @@ seahorse_gconf_set_boolean (const char *key, gboolean boolean_value)
handle_error (&error);
}
+/**
+ * seahorse_gconf_get_boolean:
+ * @key: The key to read
+ *
+ * Read a boolean key from the GConf storage
+ *
+ * Returns: It returns the read value. On error it returns FALSE
+ */
gboolean
seahorse_gconf_get_boolean (const char *key)
{
@@ -124,6 +169,15 @@ seahorse_gconf_get_boolean (const char *key)
return handle_error (&error) ? FALSE : result;
}
+/**
+ * seahorse_gconf_set_integer:
+ * @key: The key
+ * @int_value: The value to set
+ *
+ * Set a value for an integer key in the GConf storage
+ *
+ * Errors are handled internally and are mapped to a warning
+ */
void
seahorse_gconf_set_integer (const char *key, int int_value)
{
@@ -139,6 +193,14 @@ seahorse_gconf_set_integer (const char *key, int int_value)
handle_error (&error);
}
+/**
+ * seahorse_gconf_get_integer:
+ * @key: The key to read
+ *
+ * Read an integer key from the GConf storage
+ *
+ * Returns: It returns the read value. On error it returns 0.
+ */
int
seahorse_gconf_get_integer (const char *key)
{
@@ -155,6 +217,16 @@ seahorse_gconf_get_integer (const char *key)
return handle_error (&error) ? 0 : result;
}
+
+/**
+ * seahorse_gconf_set_string:
+ * @key: The key
+ * @string_value: The value to set
+ *
+ * Set a value for a string key in the GConf storage
+ *
+ * Errors are handled internally and are mapped to a warning
+ */
void
seahorse_gconf_set_string (const char *key, const char *string_value)
{
@@ -170,6 +242,15 @@ seahorse_gconf_set_string (const char *key, const char *string_value)
handle_error (&error);
}
+/**
+ * seahorse_gconf_get_string:
+ * @key: The key to read
+ *
+ * Read a string key from the GConf storage
+ *
+ * Returns: It returns the read value. On error it returns "". The returned string should be
+ * freed with #g_free when no longer needed.
+ */
char *
seahorse_gconf_get_string (const char *key)
{
@@ -186,6 +267,15 @@ seahorse_gconf_get_string (const char *key)
return handle_error (&error) ? g_strdup ("") : result;
}
+/**
+ * seahorse_gconf_set_string_list:
+ * @key: The key
+ * @slist: The list to set
+ *
+ * Set a value for a string list (linked list of strings) key in the GConf storage
+ *
+ * Errors are handled internally and are mapped to a warning
+ */
void
seahorse_gconf_set_string_list (const char *key, const GSList *slist)
{
@@ -202,6 +292,16 @@ seahorse_gconf_set_string_list (const char *key, const GSList *slist)
handle_error (&error);
}
+/**
+ * seahorse_gconf_get_string_list:
+ * @key: The key to read
+ *
+ * Read a string list (linked list of strings) key from the GConf storage
+ *
+ * Returns: It returns the read value. On error it returns NULL. Each returned
+ * string should be freed with #g_free when no longer needed. The list must be
+ * freed with #g_slist_free
+ */
GSList*
seahorse_gconf_get_string_list (const char *key)
{
@@ -218,6 +318,15 @@ seahorse_gconf_get_string_list (const char *key)
return handle_error (&error) ? NULL : slist;
}
+/**
+ * seahorse_gconf_get_entry:
+ * @key: The key to read
+ *
+ * Get an entry key from the GConf storage
+ *
+ * Returns: It returns the read value. On error it returns NULL. Must be freed
+ * with #gconf_entry_free
+ */
GConfEntry*
seahorse_gconf_get_entry (const char *key)
{
@@ -234,6 +343,14 @@ seahorse_gconf_get_entry (const char *key)
return handle_error (&error) ? NULL : entry;
}
+/**
+ * seahorse_gconf_notify:
+ * @key: The key to add the notification for
+ * @notification_callback: The callback function to add
+ * @callback_data: user data to pass to the callback function
+ *
+ * Returns: The connection ID. On error it returns 0
+ */
guint
seahorse_gconf_notify (const char *key, GConfClientNotifyFunc notification_callback,
gpointer callback_data)
@@ -261,6 +378,12 @@ seahorse_gconf_notify (const char *key, GConfClientNotifyFunc notification_callb
return notification_id;
}
+/**
+ * internal_gconf_unnotify:
+ * @data: Casts the pointer to an integer ID and removes the notification with
+ * this ID
+ *
+ */
static void
internal_gconf_unnotify (gpointer data)
{
@@ -268,6 +391,18 @@ internal_gconf_unnotify (gpointer data)
seahorse_gconf_unnotify (notify_id);
}
+/**
+ * seahorse_gconf_notify_lazy:
+ * @key: The key to add the notification for
+ * @notification_callback: The callback function to add
+ * @callback_data: user data to pass to the callback function
+ * @lifetime: a GObject to bind the callback to
+ *
+ * The callback is bound to the object (#g_object_set_data_full) and
+ * the notification is automatically unnotified as soon as the object is
+ * destroyed
+ *
+ */
void
seahorse_gconf_notify_lazy (const char *key, GConfClientNotifyFunc notification_callback,
gpointer callback_data, gpointer lifetime)
@@ -283,6 +418,12 @@ seahorse_gconf_notify_lazy (const char *key, GConfClientNotifyFunc notification_
}
}
+/**
+ * seahorse_gconf_unnotify:
+ * @notification_id: ID to remove
+ *
+ * Removes a notification identified by the ID
+ */
void
seahorse_gconf_unnotify (guint notification_id)
{
diff --git a/libseahorse/seahorse-gtkstock.c b/libseahorse/seahorse-gtkstock.c
index 5f66aea..564537a 100644
--- a/libseahorse/seahorse-gtkstock.c
+++ b/libseahorse/seahorse-gtkstock.c
@@ -49,6 +49,15 @@ static const gchar *themed_icons[] = {
NULL
};
+/**
+ * make_theme_source:
+ * @icon: The full icon file name
+ * @size: The size. If this is -1, gtk_icon_source_set_size_wildcarded will be set
+ *
+ * Creates a new GtkIconSource, containing the file icon
+ *
+ * Returns: The GtkIconSource
+ */
static GtkIconSource*
make_theme_source (const gchar *icon, GtkIconSize size)
{
@@ -69,6 +78,17 @@ make_theme_source (const gchar *icon, GtkIconSize size)
return source;
}
+/**
+ * make_icon_source:
+ * @icon: The icon name
+ * @base: Base path
+ * @ext: File extension of the icon
+ * @size: The size. If this is -1, gtk_icon_source_set_size_wildcarded will be set
+ *
+ * Creates a new GtkIconSource, containing the file PIXMAPSDIR/base/icon.ext
+ *
+ * Returns: The GtkIconSource
+ */
static GtkIconSource*
make_icon_source (const gchar *icon, const gchar *base, const gchar *ext,
GtkIconSize size)
@@ -95,6 +115,14 @@ make_icon_source (const gchar *icon, const gchar *base, const gchar *ext,
return source;
}
+
+/**
+ * add_icons:
+ * @icons: Icons to add
+ * @themed: Themed icons to add
+ *
+ * Adds different sized icons to the icon factory.
+ */
static void
add_icons (const gchar **icons, const gchar **themed)
{
@@ -169,6 +197,12 @@ add_icons (const gchar **icons, const gchar **themed)
g_object_unref (factory);
}
+/**
+ * seahorse_gtkstock_init:
+ *
+ * Adds the default icons to the icon factory
+ *
+ */
void
seahorse_gtkstock_init(void)
{
@@ -183,6 +217,12 @@ seahorse_gtkstock_init(void)
add_icons (seahorse_icons, themed_icons);
}
+/**
+ * seahorse_gtkstock_add_icons:
+ * @icons: The icons to add to the default factory
+ *
+ * Adds icons to the factory
+ */
void
seahorse_gtkstock_add_icons (const gchar **icons)
{
diff --git a/libseahorse/seahorse-object.c b/libseahorse/seahorse-object.c
index d13632d..ce12c14 100644
--- a/libseahorse/seahorse-object.c
+++ b/libseahorse/seahorse-object.c
@@ -30,6 +30,24 @@
#include <glib/gi18n.h>
+/**
+ * @PROP_0:
+ * @PROP_CONTEXT:
+ * @PROP_SOURCE:
+ * @PROP_PREFERRED:
+ * @PROP_PARENT:
+ * @PROP_ID:
+ * @PROP_TAG:
+ * @PROP_LABEL:
+ * @PROP_MARKUP:
+ * @PROP_NICKNAME:
+ * @PROP_DESCRIPTION:
+ * @PROP_ICON:
+ * @PROP_IDENTIFIER:
+ * @PROP_LOCATION:
+ * @PROP_USAGE:
+ * @PROP_FLAGS:
+ */
enum {
PROP_0,
PROP_CONTEXT,
@@ -49,6 +67,32 @@ enum {
PROP_FLAGS
};
+/**
+ * _SeahorseObjectPrivate:
+ * @id: the id of the object
+ * @tag: DBUS: "ktype"
+ * @tag_explicit: If TRUE the tag will not be set automatically
+ * @source: Where did the object come from ?
+ * @context:
+ * @preferred: Points to the object to prefer over this one
+ * @parent: the object's parent
+ * @children: a list of children the object has
+ * @label: DBUS: "display-name"
+ * @markup: Markup text
+ * @markup_explicit: If TRUE the markup will not be set automatically
+ * @nickname: DBUS: "simple-name"
+ * @nickname_explicit: If TRUE the nickname will not be set automatically
+ * @description: Description text DBUS: "key-desc"
+ * @description_explicit: If TRUE the description will not be set automatically
+ * @icon: DBUS: "stock-id"
+ * @identifier: DBUS: "key-id", "display-id", "raw-id"
+ * @identifier_explicit:
+ * @location: describes the loaction of the object (local, remte, invalid...)
+ * @usage: DBUS: "etype"
+ * @flags:
+ * @realizing: set while the object is realizing
+ * @realized: set as soon as the object is realized
+ */
struct _SeahorseObjectPrivate {
GQuark id;
GQuark tag;
@@ -60,21 +104,21 @@ struct _SeahorseObjectPrivate {
SeahorseObject *parent;
GList *children;
- gchar *label;
- gchar *markup;
- gboolean markup_explicit;
- gchar *nickname;
- gboolean nickname_explicit;
- gchar *description;
- gboolean description_explicit;
- gchar *icon;
- gchar *identifier;
- gboolean identifier_explicit;
-
- SeahorseLocation location;
- SeahorseUsage usage;
- guint flags;
-
+ gchar *label;
+ gchar *markup;
+ gboolean markup_explicit;
+ gchar *nickname;
+ gboolean nickname_explicit;
+ gchar *description;
+ gboolean description_explicit;
+ gchar *icon;
+ gchar *identifier;
+ gboolean identifier_explicit;
+
+ SeahorseLocation location;
+ SeahorseUsage usage;
+ guint flags;
+
gboolean realized;
gboolean realizing;
};
@@ -85,6 +129,14 @@ G_DEFINE_TYPE (SeahorseObject, seahorse_object, G_TYPE_OBJECT);
* INTERNAL
*/
+/**
+ * register_child:
+ * @self: The parent
+ * @child: The new child
+ *
+ *
+ * Sets @child as a child of @self
+ */
static void
register_child (SeahorseObject* self, SeahorseObject* child)
{
@@ -97,6 +149,14 @@ register_child (SeahorseObject* self, SeahorseObject* child)
self->pv->children = g_list_append (self->pv->children, child);
}
+/**
+ * unregister_child:
+ * @self: The parent
+ * @child: child to remove
+ *
+ *
+ * removes @child from the children list in @self
+ */
static void
unregister_child (SeahorseObject* self, SeahorseObject* child)
{
@@ -109,6 +169,15 @@ unregister_child (SeahorseObject* self, SeahorseObject* child)
self->pv->children = g_list_remove (self->pv->children, child);
}
+/**
+ * set_string_storage:
+ * @value: The value to store
+ * @storage: The datastore to write the value to
+ *
+ * When storing, new memory will be allocated and the value copied
+ *
+ * Returns: TRUE if the value has been set new, FALSE else
+ */
static gboolean
set_string_storage (const gchar *value, gchar **storage)
{
@@ -126,6 +195,15 @@ set_string_storage (const gchar *value, gchar **storage)
return FALSE;
}
+/**
+ * take_string_storage:
+ * @value: The value to store
+ * @storage: The datastore to write the value to
+ *
+ * When storing, the pointer to value is used. No new memory will be allocated
+ *
+ * Returns: TRUE if the value has been set new, FALSE else
+ */
static gboolean
take_string_storage (gchar *value, gchar **storage)
{
@@ -144,6 +222,13 @@ take_string_storage (gchar *value, gchar **storage)
return FALSE;
}
+/**
+ * recalculate_id:
+ * @self: object to calculate for
+ *
+ * recalculates tag and identifier from id
+ *
+ */
static void
recalculate_id (SeahorseObject *self)
{
@@ -189,6 +274,13 @@ recalculate_id (SeahorseObject *self)
}
}
+/**
+ * recalculate_label:
+ * @self: object to recalculate label for
+ *
+ * Recalculates nickname and markup from the label
+ *
+ */
static void
recalculate_label (SeahorseObject *self)
{
@@ -204,6 +296,14 @@ recalculate_label (SeahorseObject *self)
}
}
+/**
+ * recalculate_usage:
+ * @self: The #SeahorseObject to recalculate the usage decription for
+ *
+ * Basing on the usage identifiere this function will calculate a usage
+ * description and store it in the object.
+ *
+ */
static void
recalculate_usage (SeahorseObject *self)
{
@@ -246,6 +346,13 @@ recalculate_usage (SeahorseObject *self)
* OBJECT
*/
+/**
+ * seahorse_object_init:
+ * @self: The object to initialise
+ *
+ * Initialises the object with default data
+ *
+ */
static void
seahorse_object_init (SeahorseObject *self)
{
@@ -260,6 +367,14 @@ seahorse_object_init (SeahorseObject *self)
self->pv->usage = SEAHORSE_USAGE_NONE;
}
+
+/**
+ * seahorse_object_dispose:
+ * @obj: A #SeahorseObject to dispose
+ *
+ * Before this object is disposed, all it's children get new parents
+ *
+ */
static void
seahorse_object_dispose (GObject *obj)
{
@@ -308,6 +423,11 @@ seahorse_object_dispose (GObject *obj)
G_OBJECT_CLASS (seahorse_object_parent_class)->dispose (obj);
}
+/**
+ * seahorse_object_finalize:
+ * @obj: #SeahorseObject to finalize
+ *
+ */
static void
seahorse_object_finalize (GObject *obj)
{
@@ -340,6 +460,17 @@ seahorse_object_finalize (GObject *obj)
G_OBJECT_CLASS (seahorse_object_parent_class)->finalize (obj);
}
+
+/**
+ * seahorse_object_get_property:
+ * @obj: The object to get the property for
+ * @prop_id: The property requested
+ * @value: out - the value as #GValue
+ * @pspec: a #GParamSpec for the warning
+ *
+ * Returns: The property of the object @obj defined by the id @prop_id in @value.
+ *
+ */
static void
seahorse_object_get_property (GObject *obj, guint prop_id, GValue *value,
GParamSpec *pspec)
@@ -398,6 +529,16 @@ seahorse_object_get_property (GObject *obj, guint prop_id, GValue *value,
}
}
+/**
+ * seahorse_object_set_property:
+ * @obj: Object to set the property in
+ * @prop_id: the property to set
+ * @value: the value to set
+ * @pspec: To be used for warnings. #GParamSpec
+ *
+ * Sets a property in this object
+ *
+ */
static void
seahorse_object_set_property (GObject *obj, guint prop_id, const GValue *value,
GParamSpec *pspec)
@@ -514,6 +655,13 @@ seahorse_object_set_property (GObject *obj, guint prop_id, const GValue *value,
}
}
+/**
+ * seahorse_object_real_realize:
+ * @self: The object
+ *
+ * To be overridden
+ *
+ */
static void
seahorse_object_real_realize (SeahorseObject *self)
{
@@ -525,6 +673,13 @@ seahorse_object_real_realize (SeahorseObject *self)
self->pv->realized = TRUE;
}
+/**
+ * seahorse_object_real_refresh:
+ * @self: The object
+ *
+ * To be overridden
+ *
+ */
static void
seahorse_object_real_refresh (SeahorseObject *self)
{
@@ -534,6 +689,13 @@ seahorse_object_real_refresh (SeahorseObject *self)
*/
}
+/**
+ * seahorse_object_class_init:
+ * @klass: the object class
+ *
+ * Initialises the object class
+ *
+ */
static void
seahorse_object_class_init (SeahorseObjectClass *klass)
{
@@ -615,6 +777,12 @@ seahorse_object_class_init (SeahorseObjectClass *klass)
* PUBLIC
*/
+/**
+ * seahorse_object_get_id:
+ * @self: Object
+ *
+ * Returns: the id of the object @self
+ */
GQuark
seahorse_object_get_id (SeahorseObject *self)
{
@@ -622,6 +790,12 @@ seahorse_object_get_id (SeahorseObject *self)
return self->pv->id;
}
+/**
+ * seahorse_object_get_tag:
+ * @self: Object
+ *
+ * Returns: the tag of the object @self
+ */
GQuark
seahorse_object_get_tag (SeahorseObject *self)
{
@@ -631,6 +805,12 @@ seahorse_object_get_tag (SeahorseObject *self)
return self->pv->tag;
}
+/**
+ * seahorse_object_get_source:
+ * @self: Object
+ *
+ * Returns: the source of the object @self
+ */
SeahorseSource*
seahorse_object_get_source (SeahorseObject *self)
{
@@ -638,6 +818,14 @@ seahorse_object_get_source (SeahorseObject *self)
return self->pv->source;
}
+
+/**
+ * seahorse_object_set_source:
+ * @self: The object to set a new source for
+ * @value: The source to set
+ *
+ * sets the source for the object
+ */
void
seahorse_object_set_source (SeahorseObject *self, SeahorseSource *value)
{
@@ -656,6 +844,12 @@ seahorse_object_set_source (SeahorseObject *self, SeahorseSource *value)
g_object_notify (G_OBJECT (self), "source");
}
+/**
+ * seahorse_object_get_context:
+ * @self: Object
+ *
+ * Returns: the context of the object @self
+ */
SeahorseContext*
seahorse_object_get_context (SeahorseObject *self)
{
@@ -663,6 +857,12 @@ seahorse_object_get_context (SeahorseObject *self)
return self->pv->context;
}
+/**
+ * seahorse_object_get_preferred:
+ * @self: Object
+ *
+ * Returns: the preferred of the object @self
+ */
SeahorseObject*
seahorse_object_get_preferred (SeahorseObject *self)
{
@@ -670,6 +870,13 @@ seahorse_object_get_preferred (SeahorseObject *self)
return self->pv->preferred;
}
+/**
+ * seahorse_object_set_preferred:
+ * @self: the object to set the preferred object for
+ * @value: the preferred object
+ *
+ *
+ */
void
seahorse_object_set_preferred (SeahorseObject *self, SeahorseObject *value)
{
@@ -688,6 +895,12 @@ seahorse_object_set_preferred (SeahorseObject *self, SeahorseObject *value)
g_object_notify (G_OBJECT (self), "preferred");
}
+/**
+ * seahorse_object_get_parent:
+ * @self: Object
+ *
+ * Returns: the parent of the object @self
+ */
SeahorseObject*
seahorse_object_get_parent (SeahorseObject *self)
{
@@ -695,6 +908,13 @@ seahorse_object_get_parent (SeahorseObject *self)
return self->pv->parent;
}
+/**
+ * seahorse_object_set_parent:
+ * @self: the child
+ * @value: the parent
+ *
+ * register @value as the parent of @self:
+ */
void
seahorse_object_set_parent (SeahorseObject *self, SeahorseObject *value)
{
@@ -716,7 +936,13 @@ seahorse_object_set_parent (SeahorseObject *self, SeahorseObject *value)
g_object_notify (G_OBJECT (self), "parent");
}
-
+
+/**
+ * seahorse_object_get_children:
+ * @self: Object
+ *
+ * Returns: the children of the object @self
+ */
GList*
seahorse_object_get_children (SeahorseObject *self)
{
@@ -725,6 +951,13 @@ seahorse_object_get_children (SeahorseObject *self)
return g_list_copy (self->pv->children);
}
+/**
+ * seahorse_object_get_nth_child:
+ * @self: Object
+ * @index: the number of the child to return
+ *
+ * Returns: the child number @index
+ */
SeahorseObject*
seahorse_object_get_nth_child (SeahorseObject *self, guint index)
{
@@ -732,6 +965,12 @@ seahorse_object_get_nth_child (SeahorseObject *self, guint index)
return SEAHORSE_OBJECT (g_list_nth_data (self->pv->children, index));
}
+/**
+ * seahorse_object_get_label:
+ * @self: Object
+ *
+ * Returns: the label of the object @self
+ */
const gchar*
seahorse_object_get_label (SeahorseObject *self)
{
@@ -740,6 +979,12 @@ seahorse_object_get_label (SeahorseObject *self)
return self->pv->label;
}
+/**
+ * seahorse_object_get_markup:
+ * @self: Object
+ *
+ * Returns: the markup of the object @self
+ */
const gchar*
seahorse_object_get_markup (SeahorseObject *self)
{
@@ -748,6 +993,12 @@ seahorse_object_get_markup (SeahorseObject *self)
return self->pv->markup;
}
+/**
+ * seahorse_object_get_nickname:
+ * @self: Object
+ *
+ * Returns: the nickname of the object @self
+ */
const gchar*
seahorse_object_get_nickname (SeahorseObject *self)
{
@@ -756,6 +1007,12 @@ seahorse_object_get_nickname (SeahorseObject *self)
return self->pv->nickname;
}
+/**
+ * seahorse_object_get_description:
+ * @self: Object
+ *
+ * Returns: the description of the object @self
+ */
const gchar*
seahorse_object_get_description (SeahorseObject *self)
{
@@ -764,6 +1021,12 @@ seahorse_object_get_description (SeahorseObject *self)
return self->pv->description;
}
+/**
+ * seahorse_object_get_icon:
+ * @self: Object
+ *
+ * Returns: the icon of the object @self
+ */
const gchar*
seahorse_object_get_icon (SeahorseObject *self)
{
@@ -772,6 +1035,12 @@ seahorse_object_get_icon (SeahorseObject *self)
return self->pv->icon;
}
+/**
+ * seahorse_object_get_identifier:
+ * @self: Object
+ *
+ * Returns: the identifier of the object @self
+ */
const gchar*
seahorse_object_get_identifier (SeahorseObject *self)
{
@@ -780,6 +1049,12 @@ seahorse_object_get_identifier (SeahorseObject *self)
return self->pv->identifier;
}
+/**
+ * seahorse_object_get_location:
+ * @self: Object
+ *
+ * Returns: the location of the object @self
+ */
SeahorseLocation
seahorse_object_get_location (SeahorseObject *self)
{
@@ -789,6 +1064,12 @@ seahorse_object_get_location (SeahorseObject *self)
return self->pv->location;
}
+/**
+ * seahorse_object_get_usage:
+ * @self: Object
+ *
+ * Returns: the usage of the object @self
+ */
SeahorseUsage
seahorse_object_get_usage (SeahorseObject *self)
{
@@ -798,6 +1079,12 @@ seahorse_object_get_usage (SeahorseObject *self)
return self->pv->usage;
}
+/**
+ * seahorse_object_get_flags:
+ * @self: Object
+ *
+ * Returns: the flags of the object @self
+ */
guint
seahorse_object_get_flags (SeahorseObject *self)
{
@@ -806,6 +1093,16 @@ seahorse_object_get_flags (SeahorseObject *self)
return self->pv->flags;
}
+/**
+ * seahorse_object_lookup_property:
+ * @self: the object to look up the property
+ * @field: the field to lookup
+ * @value: the returned value
+ *
+ * Looks up the property @field in the object @self and returns it in @value
+ *
+ * Returns: TRUE if a property was found
+ */
gboolean
seahorse_object_lookup_property (SeahorseObject *self, const gchar *field, GValue *value)
{
@@ -850,6 +1147,13 @@ seahorse_object_lookup_property (SeahorseObject *self, const gchar *field, GValu
return TRUE;
}
+/**
+ * seahorse_object_realize:
+ * @self: the object to realize
+ *
+ *
+ * Realizes an object. Calls the klass method
+ */
void
seahorse_object_realize (SeahorseObject *self)
{
@@ -866,6 +1170,13 @@ seahorse_object_realize (SeahorseObject *self)
self->pv->realizing = FALSE;
}
+/**
+ * seahorse_object_refresh:
+ * @self: object to refresh
+ *
+ * calls the class refresh function
+ *
+ */
void
seahorse_object_refresh (SeahorseObject *self)
{
@@ -876,6 +1187,14 @@ seahorse_object_refresh (SeahorseObject *self)
(klass->refresh) (self);
}
+/**
+ * seahorse_object_delete:
+ * @self: object to delete
+ *
+ * calls the class delete function
+ *
+ * Returns: NULL on error
+ */
SeahorseOperation*
seahorse_object_delete (SeahorseObject *self)
{
@@ -886,6 +1205,15 @@ seahorse_object_delete (SeahorseObject *self)
return (klass->delete) (self);
}
+/**
+ * seahorse_object_predicate_match:
+ * @self: the object to test
+ * @obj: The predicate to match
+ *
+ * matches a seahorse object and a predicate
+ *
+ * Returns: FALSE if predicate does not match the #SeahorseObject, TRUE else
+ */
gboolean
seahorse_object_predicate_match (SeahorseObjectPredicate *self, SeahorseObject* obj)
{
@@ -921,6 +1249,12 @@ seahorse_object_predicate_match (SeahorseObjectPredicate *self, SeahorseObject*
return TRUE;
}
+/**
+ * seahorse_object_predicate_clear:
+ * @self: The predicate to clean
+ *
+ * Clears a seahorse predicate (#SeahorseObjectPredicate)
+ */
void
seahorse_object_predicate_clear (SeahorseObjectPredicate *self)
{
diff --git a/libseahorse/seahorse-prefs.c b/libseahorse/seahorse-prefs.c
index 6588207..d501c8a 100644
--- a/libseahorse/seahorse-prefs.c
+++ b/libseahorse/seahorse-prefs.c
@@ -502,6 +502,8 @@ seahorse_prefs_new (GtkWindow *parent)
/**
* seahorse_prefs_add_tab
* @swidget: The preferences window
+ * @label: Label for the tab to be added
+ * @tab: Tab to be added
*
* Add a tab to the preferences window
**/
@@ -514,6 +516,13 @@ seahorse_prefs_add_tab (SeahorseWidget *swidget, GtkWidget *label, GtkWidget *ta
gtk_notebook_prepend_page (GTK_NOTEBOOK (widget), tab, label);
}
+/**
+ * seahorse_prefs_select_tab:
+ * @swidget: The preferences window
+ * @tab: The tab to be set active
+ *
+ * Sets the input tab to be the active one
+ **/
void
seahorse_prefs_select_tab (SeahorseWidget *swidget, GtkWidget *tab)
{
@@ -530,6 +539,13 @@ seahorse_prefs_select_tab (SeahorseWidget *swidget, GtkWidget *tab)
gtk_notebook_set_current_page (GTK_NOTEBOOK (tabs), pos);
}
+/**
+ * seahorse_prefs_remove_tab:
+ * @swidget: The preferences window
+ * @tab: The tab to be removed
+ *
+ * Removes a tab from the preferences window
+ **/
void
seahorse_prefs_remove_tab (SeahorseWidget *swidget, GtkWidget *tab)
{
diff --git a/libseahorse/seahorse-secure-memory.c b/libseahorse/seahorse-secure-memory.c
index e55ba8a..32a1f56 100644
--- a/libseahorse/seahorse-secure-memory.c
+++ b/libseahorse/seahorse-secure-memory.c
@@ -33,6 +33,15 @@
/* extern declared in seahorse-secure-memory.h */
gboolean seahorse_use_secure_mem = FALSE;
+/**
+ * switch_malloc:
+ * @size: The size of the new memory buffer
+ *
+ * Transparent alternative. Depending on the setting for secure memory, the
+ * function calls the default-C version or the GTK version for non-pageable memory
+ *
+ * Returns: The pointer to the new buffer
+ */
static gpointer
switch_malloc (gsize size)
{
@@ -47,6 +56,16 @@ switch_malloc (gsize size)
return p;
}
+/**
+ * switch_calloc:
+ * @num: Number of blocks to allocate
+ * @size: Size of a block
+ *
+ * Transparent alternative. Depending on the setting for secure memory, the
+ * function calls the default-C version or the GTK version for non-pageable memory
+ *
+ * Returns: The pointer to a buffer sized num*size
+ */
static gpointer
switch_calloc (gsize num, gsize size)
{
@@ -61,6 +80,16 @@ switch_calloc (gsize num, gsize size)
return p;
}
+/**
+ * switch_realloc:
+ * @mem: The old memory to resize
+ * @size: The new size
+ *
+ * Transparent alternative. Depending on the setting for secure memory, the
+ * function calls the default-C version or the GTK version for non-pageable memory
+ *
+ * Returns: The pointer to the resized memory
+ */
static gpointer
switch_realloc (gpointer mem, gsize size)
{
@@ -83,6 +112,13 @@ switch_realloc (gpointer mem, gsize size)
return p;
}
+/**
+ * switch_free:
+ * @mem: The memory to free
+ *
+ * Transparent alternative. Depending on the setting for secure memory, the
+ * function calls the default-C version or the GTK version for non-pageable memory
+ */
static void
switch_free (gpointer mem)
{
@@ -94,6 +130,12 @@ switch_free (gpointer mem)
}
}
+/**
+ * seahorse_try_gk_secure_memory:
+ *
+ *
+ * Returns: TRUE if non-pageable memory is available
+ */
static gboolean
seahorse_try_gk_secure_memory ()
{
@@ -108,6 +150,16 @@ seahorse_try_gk_secure_memory ()
return FALSE;
}
+/**
+ * seahorse_secure_memory_init:
+ *
+ * Configures non-pageable (secure) memory. Must be called before the first
+ * memory allocation.
+ *
+ * This function sets the #GMemVTable to use the switch* function implemented in
+ * this files
+ *
+ */
void
seahorse_secure_memory_init ()
{
diff --git a/libseahorse/seahorse-util.c b/libseahorse/seahorse-util.c
index fffe464..6f377f8 100644
--- a/libseahorse/seahorse-util.c
+++ b/libseahorse/seahorse-util.c
@@ -50,6 +50,17 @@
static const gchar *bad_filename_chars = "/\\<>|";
+/**
+ * seahorse_util_show_error:
+ * @parent: The parent widget. Can be NULL
+ * @heading: The heading of the dialog
+ * @message: The message to display
+ *
+ * This displays an error dialog.
+ * The parent widget can be any widget. The dialog will be a child of the window
+ * the widget is in.
+ *
+ */
void
seahorse_util_show_error (GtkWidget *parent, const gchar *heading, const gchar *message)
{
@@ -89,6 +100,14 @@ seahorse_util_show_error (GtkWidget *parent, const gchar *heading, const gchar *
gtk_widget_destroy (dialog);
}
+/**
+ * seahorse_util_handle_error:
+ * @err: The #GError to print.
+ * @desc: The heading of the box
+ * @...: Parameters to insert into the format string desc.
+ *
+ * Displays an error box. The message is the error message.
+ */
void
seahorse_util_handle_error (GError* err, const char* desc, ...)
{
@@ -110,6 +129,15 @@ seahorse_util_handle_error (GError* err, const char* desc, ...)
g_free(t);
}
+/**
+ * seahorse_util_prompt_delete:
+ * @text: The text to display in the delete-dialog
+ * @parent: The widget to display the dialog for. Can be NULL
+ *
+ * Displays a modal dialog with "cancel" and "delete"
+ *
+ * Returns: TRUE if the user pressed "delete", FALSE else
+ */
gboolean
seahorse_util_prompt_delete (const gchar *text, GtkWidget *parent)
{
@@ -147,7 +175,8 @@ seahorse_util_prompt_delete (const gchar *text, GtkWidget *parent)
}
/**
- * seahorse_util_error_domain
+ * seahorse_util_error_domain:
+ *
* Returns: The GError domain for generic seahorse errors
**/
GQuark
@@ -165,7 +194,8 @@ seahorse_util_error_domain ()
*
* Creates a string representation of @time for use with gpg.
*
- * Returns: A string representing @time
+ * Returns: A string representing @time. The returned string should be freed
+ * with #g_free when no longer needed.
**/
gchar*
seahorse_util_get_date_string (const time_t time)
@@ -189,7 +219,8 @@ seahorse_util_get_date_string (const time_t time)
*
* Creates a string representation of @time for display in the UI.
*
- * Returns: A string representing @time
+ * Returns: A string representing @time. The returned string should be freed
+ * with #g_free when no longer needed.
**/
gchar*
seahorse_util_get_display_date_string (const time_t time)
@@ -207,6 +238,15 @@ seahorse_util_get_display_date_string (const time_t time)
return created_string;
}
+/**
+ * seahorse_util_get_text_view_text:
+ * @view: The text view #GtkTextView to extract text from
+ *
+ * Returns the whole text buffer
+ *
+ * Returns: The text buffer extracted. The returned string should be freed with
+ * #g_free when no longer needed.
+ */
gchar*
seahorse_util_get_text_view_text (GtkTextView *view)
{
@@ -223,6 +263,13 @@ seahorse_util_get_text_view_text (GtkTextView *view)
return text;
}
+/**
+ * seahorse_util_set_text_view_string:
+ * @view: The view to set the text for (#GtkTextView)
+ * @string: The string to set (#GString)
+ *
+ *
+ */
void
seahorse_util_set_text_view_string (GtkTextView *view, GString *string)
{
@@ -235,12 +282,13 @@ seahorse_util_set_text_view_string (GtkTextView *view, GString *string)
/**
* seahorse_util_read_to_memory:
- * @data: Data to write
- * @len: Length of the data
+ * @input: Data to read. The #GInputStream is read till the end.
+ * @len: Length of the data read (out)
*
- * Converts @data to a string.
+ * Reads data from the input stream and returns them as #guchar
*
- * Returns: The string read from data
+ * Returns: The string read from data. The returned string should be freed
+ * with #g_free when no longer needed.
**/
guchar*
seahorse_util_read_to_memory (GInputStream *input, guint *len)
@@ -272,15 +320,14 @@ seahorse_util_read_to_memory (GInputStream *input, guint *len)
}
/**
- * seahorse_util_read_data_block
- *
- * Breaks out one block of data (usually a key)
- *
+ * seahorse_util_read_data_block:
* @buf: A string buffer to write the data to.
* @input: The input stream to read from.
* @start: The start signature to look for.
* @end: The end signature to look for.
- *
+ *
+ * Breaks out one block of data (usually a key)
+ *
* Returns: The number of bytes copied.
*/
guint
@@ -327,6 +374,13 @@ seahorse_util_read_data_block (GString *buf, GInputStream *input,
return copied;
}
+/**
+ * seahorse_util_memory_input_string:
+ * @string: The string to create the stream from
+ * @length: The length of this string
+ *
+ * Returns: The new input stream of type #GMemoryInputStream
+ */
GMemoryInputStream*
seahorse_util_memory_input_string (const gchar *string, gsize length)
{
@@ -334,6 +388,14 @@ seahorse_util_memory_input_string (const gchar *string, gsize length)
return G_MEMORY_INPUT_STREAM (g_memory_input_stream_new_from_data (g_strndup (string, length), length, g_free));
}
+/**
+ * seahorse_util_memory_output_length:
+ * @output: a stream
+ *
+ * A replacement for #g_memory_output_stream_get_data_size (since 2.18)
+ *
+ * Returns: The length of the stream
+ */
gsize
seahorse_util_memory_output_length (GMemoryOutputStream *output)
{
@@ -367,9 +429,9 @@ seahorse_util_memory_output_length (GMemoryOutputStream *output)
/**
* seahorse_util_printf_fd:
* @fd: The file descriptor to write to
- * @fmt: The data to write
+ * @s: The data to write
*
- * Returns: Whether the operation was successful or not.
+ * Returns: FALSE on error, TRUE on success
**/
gboolean
seahorse_util_print_fd (int fd, const char* s)
@@ -402,8 +464,9 @@ seahorse_util_print_fd (int fd, const char* s)
* seahorse_util_printf_fd:
* @fd: The file descriptor to write to
* @fmt: The printf format of the data to write
+ * @...: The parameters to insert
*
- * Returns: Whether the operation was successful or not.
+ * Returns: TRUE on success, FALSE on error
**/
gboolean
seahorse_util_printf_fd (int fd, const char* fmt, ...)
@@ -421,7 +484,18 @@ seahorse_util_printf_fd (int fd, const char* fmt, ...)
return ret;
}
-
+/**
+ * seahorse_util_filename_for_objects:
+ * @objects: A list of objects
+ *
+ * If the single object has a nickname, this will be returned (with .asc attached)
+ * If there are multiple objects, "Multiple Keys.asc" will be returned.
+ * Single objects default to "Key Data.asc".
+ * Results are internationalized
+ *
+ * Returns: NULL on error, the filename else. The returned string should be
+ * freed with #g_free when no longer needed.
+ */
gchar*
seahorse_util_filename_for_objects (GList *objects)
{
@@ -476,7 +550,7 @@ seahorse_util_uri_get_last (const gchar* uri)
}
/**
- * seahorse_util_uri_split_last
+ * seahorse_util_uri_split_last:
* @uri: The uri to split
*
* Splits the uri in two at it's last component. The result
@@ -498,12 +572,12 @@ seahorse_util_uri_split_last (gchar* uri)
}
/**
- * seahurse_util_uri_exists
+ * seahorse_util_uri_exists:
* @uri: The uri to check
*
* Verify whether a given uri exists or not.
*
- * Returns: Whether it exists or not.
+ * Returns: FALSE if it does not exist, TRUE else
**/
gboolean
seahorse_util_uri_exists (const gchar* uri)
@@ -521,7 +595,7 @@ seahorse_util_uri_exists (const gchar* uri)
}
/**
- * seahorse_util_uri_unique
+ * seahorse_util_uri_unique:
* @uri: The uri to guarantee is unique
*
* Creates a URI based on @uri that does not exist.
@@ -580,13 +654,14 @@ seahorse_util_uri_unique (const gchar* uri)
}
/**
- * seahorse_util_uri_replace_ext
+ * seahorse_util_uri_replace_ext:
* @uri: The uri with old extension
* @ext: The new extension
- *
+ *
* Replaces the extension on @uri
- *
- * Returns: Newly allocated URI string with new extension.
+ *
+ * Returns: Newly allocated URI string with new extension. The returned string
+ * should be freed with #g_free when no longer needed.
**/
gchar*
seahorse_util_uri_replace_ext (const gchar *uri, const gchar *ext)
@@ -623,13 +698,13 @@ seahorse_util_uri_replace_ext (const gchar *uri, const gchar *ext)
}
/**
- * seahorse_util_uris_package
+ * seahorse_util_uris_package:
* @package: Package uri
* @uris: null-terminated array of uris to package
*
* Package uris into an archive. The uris must be local.
*
- * Returns: Success or failure
+ * Returns: TRUE on success or FALSE on failure
*/
gboolean
seahorse_util_uris_package (const gchar* package, const char** uris)
@@ -707,6 +782,14 @@ seahorse_util_uris_package (const gchar* package, const char** uris)
return TRUE;
}
+/**
+ * seahorse_util_detect_mime_type:
+ * @mime: The mime string
+ *
+ * Return the mime type depending on the mime string
+ *
+ * Returns: SEAHORSE_PGP, SEAHORSE_SSH or 0
+ */
GQuark
seahorse_util_detect_mime_type (const gchar *mime)
{
@@ -730,6 +813,13 @@ seahorse_util_detect_mime_type (const gchar *mime)
return 0;
}
+/**
+ * seahorse_util_detect_data_type:
+ * @data: The buffer to test for content type
+ * @length: The length of this buffer
+ *
+ * Returns: SEAHORSE_PGP, SEAHORSE_SSH or 0
+ */
GQuark
seahorse_util_detect_data_type (const gchar *data, guint length)
{
@@ -746,6 +836,12 @@ seahorse_util_detect_data_type (const gchar *data, guint length)
return type;
}
+/**
+ * seahorse_util_detect_file_type:
+ * @uri: The file uri to test for content type
+ *
+ * Returns: SEAHORSE_PGP, SEAHORSE_SSH or 0
+ */
GQuark
seahorse_util_detect_file_type (const gchar *uri)
{
@@ -762,6 +858,14 @@ seahorse_util_detect_file_type (const gchar *uri)
return type;
}
+/**
+ * seahorse_util_write_file_private:
+ * @filename: file to write to
+ * @contents: nul-terminated string to write to the file
+ * @err: error of the write operation
+ *
+ * Returns: #TRUE on success, #FALSE if an error occured
+ */
gboolean
seahorse_util_write_file_private (const gchar* filename, const gchar* contents, GError **err)
{
@@ -771,6 +875,15 @@ seahorse_util_write_file_private (const gchar* filename, const gchar* contents,
return ret;
}
+/**
+ * seahorse_util_chooser_save_new:
+ * @title: The title of the dialog
+ * @parent: The parent of the dialog
+ *
+ * Creates a file chooser dialog to save files.
+ *
+ * Returns: The new save dialog
+ */
GtkDialog*
seahorse_util_chooser_save_new (const gchar *title, GtkWindow *parent)
{
@@ -787,6 +900,15 @@ seahorse_util_chooser_save_new (const gchar *title, GtkWindow *parent)
return dialog;
}
+/**
+ * seahorse_util_chooser_open_new:
+ * @title: The title of the dialog
+ * @parent: The parent of the dialog
+ *
+ * Creates a file chooser dialog to open files.
+ *
+ * Returns: The new open dialog
+ */
GtkDialog*
seahorse_util_chooser_open_new (const gchar *title, GtkWindow *parent)
{
@@ -802,6 +924,15 @@ seahorse_util_chooser_open_new (const gchar *title, GtkWindow *parent)
gtk_file_chooser_set_local_only (GTK_FILE_CHOOSER (dialog), FALSE);
return dialog;
}
+
+/**
+ * seahorse_util_chooser_show_key_files:
+ * @dialog: the dialog to add the filter for
+ *
+ * Adds a key file filter and a "All files" filter. The key filter
+ * is used.
+ *
+ */
void
seahorse_util_chooser_show_key_files (GtkDialog *dialog)
{
@@ -825,6 +956,14 @@ seahorse_util_chooser_show_key_files (GtkDialog *dialog)
gtk_file_chooser_add_filter (GTK_FILE_CHOOSER (dialog), filter);
}
+/**
+ * seahorse_util_chooser_show_archive_files:
+ * @dialog: the dialog to add the filter for
+ *
+ * Adds a archive file filter and a "All files" filter. The archive filter
+ * is used.
+ *
+ */
void
seahorse_util_chooser_show_archive_files (GtkDialog *dialog)
{
@@ -865,6 +1004,13 @@ seahorse_util_chooser_show_archive_files (GtkDialog *dialog)
gtk_file_chooser_add_filter (GTK_FILE_CHOOSER (dialog), filter);
}
+/**
+ * seahorse_util_chooser_set_filename_full:
+ * @dialog: The dialog to pre set the name
+ * @objects: generate the file name from this object
+ *
+ *
+ */
void
seahorse_util_chooser_set_filename_full (GtkDialog *dialog, GList *objects)
{
@@ -877,6 +1023,12 @@ seahorse_util_chooser_set_filename_full (GtkDialog *dialog, GList *objects)
}
}
+/**
+ * seahorse_util_chooser_set_filename:
+ * @dialog: set the dialog for this
+ * @object: The object to use for the filename. #SeahorseObject
+ *
+ */
void
seahorse_util_chooser_set_filename (GtkDialog *dialog, SeahorseObject *object)
{
@@ -884,7 +1036,15 @@ seahorse_util_chooser_set_filename (GtkDialog *dialog, SeahorseObject *object)
seahorse_util_chooser_set_filename_full (dialog, objects);
g_list_free (objects);
}
-
+
+/**
+ * seahorse_util_chooser_save_prompt:
+ * @dialog: save dialog to show
+ *
+ * If the selected file already exists, a confirmation dialog will be displayed
+ *
+ * Returns: the uri of the chosen file or NULL
+ */
gchar*
seahorse_util_chooser_save_prompt (GtkDialog *dialog)
{
@@ -925,6 +1085,14 @@ seahorse_util_chooser_save_prompt (GtkDialog *dialog)
return uri;
}
+/**
+ * seahorse_util_chooser_open_prompt:
+ * @dialog: open dialog to display
+ *
+ * Display an open dialog
+ *
+ * Returns: The uri of the file to open or NULL
+ */
gchar*
seahorse_util_chooser_open_prompt (GtkDialog *dialog)
{
@@ -940,7 +1108,7 @@ seahorse_util_chooser_open_prompt (GtkDialog *dialog)
/**
* seahorse_util_check_suffix:
* @path: Path of file to check
- * @suffix: Suffix type to check for
+ * @suffix: Suffix type to check for.
*
* Checks that @path has a suffix specified by @suffix.
*
@@ -960,7 +1128,6 @@ seahorse_util_check_suffix (const gchar *path, SeahorseSuffix suffix)
/**
* seahorse_util_add_suffix:
- * @ctx: Gpgme Context
* @path: Path of an existing file
* @suffix: Suffix type
* @prompt: Overwrite prompt text
@@ -1044,6 +1211,14 @@ seahorse_util_remove_suffix (const gchar *path, const gchar *prompt)
return uri;
}
+/**
+ * seahorse_util_strvec_dup:
+ * @vec: the string table to copy
+ *
+ * Copy a string table
+ *
+ * Returns: the new char **
+ */
gchar**
seahorse_util_strvec_dup (const gchar** vec)
{
@@ -1064,6 +1239,14 @@ seahorse_util_strvec_dup (const gchar** vec)
return ret;
}
+/**
+ * seahorse_util_strvec_length:
+ * @vec: The string table
+ *
+ * Calculates the length of the string table
+ *
+ * Returns: The length of the string table
+ */
guint
seahorse_util_strvec_length (const gchar **vec)
{
@@ -1073,6 +1256,17 @@ seahorse_util_strvec_length (const gchar **vec)
return len;
}
+
+/**
+ * sort_objects_by_source:
+ * @k1: the first seahorse object
+ * @k2: The second seahorse object
+ *
+ * Sorts the seahorse objects by their source
+ *
+ * Returns: if source of k1<k2 it returns -1,
+ * 1 will be returned if k1>k2. If the sources are equal it returns 0
+ */
static gint
sort_objects_by_source (SeahorseObject *k1, SeahorseObject *k2)
{
@@ -1090,12 +1284,30 @@ sort_objects_by_source (SeahorseObject *k1, SeahorseObject *k2)
return sk1 < sk2 ? -1 : 1;
}
+
+/**
+ * seahorse_util_objects_sort:
+ * @objects: #SeahorseObject #GList to sort
+ *
+ * The objects are sorted by their source
+ *
+ * Returns: The sorted list
+ */
GList*
seahorse_util_objects_sort (GList *objects)
{
return g_list_sort (objects, (GCompareFunc)sort_objects_by_source);
}
+
+/**
+ * seahorse_util_objects_splice:
+ * @objects: A #GList of #SeahorseObject. Must be sorted
+ *
+ * Splices the list at the source disconuity
+ *
+ * Returns: The second part of the list.
+ */
GList*
seahorse_util_objects_splice (GList *objects)
{
@@ -1128,6 +1340,15 @@ seahorse_util_objects_splice (GList *objects)
return NULL;
}
+/**
+ * seahorse_util_string_equals:
+ * @s1: String, can be NULL
+ * @s2: String, can be NULL
+ *
+ * Compares two string. If they are equal, it returns TRUE
+ *
+ * Returns: TRUE if strings are equal, FALSE else
+ */
gboolean
seahorse_util_string_equals (const gchar *s1, const gchar *s2)
{
@@ -1138,6 +1359,15 @@ seahorse_util_string_equals (const gchar *s1, const gchar *s2)
return g_str_equal (s1, s2);
}
+/**
+ * seahorse_util_string_up_first:
+ * @orig: The utf8 string to work with
+ *
+ * Upper case the first char in the UTF8 string
+ *
+ * Returns: a new string, with the first char upper cased. The returned string
+ * should be freed with #g_free when no longer needed.
+ */
gchar*
seahorse_util_string_up_first (const gchar *orig)
{
@@ -1164,7 +1394,13 @@ seahorse_util_string_up_first (const gchar *orig)
return ret;
}
-
+
+/**
+ * seahorse_util_string_lower:
+ * @s: ASCII string to change
+ *
+ * The whole ASCII string will be lower cased.
+ */
void
seahorse_util_string_lower (gchar *s)
{
@@ -1172,9 +1408,16 @@ seahorse_util_string_lower (gchar *s)
*s = g_ascii_tolower (*s);
}
-/* Free a GSList along with string values */
+/**
+ * seahorse_util_string_slist_free:
+ * @slist: the #GSList to free
+ *
+ * Free a GSList along with string values
+ *
+ * Returns: NULL
+ */
GSList*
-seahorse_util_string_slist_free (GSList *list)
+seahorse_util_string_slist_free (GSList* list)
{
GSList *l;
for (l = list; l; l = l->next)
@@ -1183,7 +1426,14 @@ seahorse_util_string_slist_free (GSList *list)
return NULL;
}
-/* Copy a GSList along with string values */
+/**
+ * seahorse_util_string_slist_copy:
+ * @slist: The list to copy
+ *
+ * Copy a #GSList along with string values
+ *
+ * Returns: the new list
+ */
GSList*
seahorse_util_string_slist_copy (GSList *list)
{
@@ -1193,7 +1443,15 @@ seahorse_util_string_slist_copy (GSList *list)
return l;
}
-/* Compare two string GSLists */
+/**
+ * seahorse_util_string_slist_equal:
+ * @sl1: the first string list
+ * @sl2: the second string list
+ *
+ * Compare two string GSLists.
+ *
+ * Returns: TRUE if all the string are equal
+ */
gboolean
seahorse_util_string_slist_equal (GSList *l1, GSList *l2)
{
@@ -1207,6 +1465,13 @@ seahorse_util_string_slist_equal (GSList *l1, GSList *l2)
return !l1 && !l2;
}
+/**
+ * seahorse_util_string_is_whitespace:
+ * @text: The UTF8 string to test
+ *
+ *
+ * Returns: TRUE if @text consists of whitespaces
+ */
gboolean
seahorse_util_string_is_whitespace (const gchar *text)
{
@@ -1221,6 +1486,12 @@ seahorse_util_string_is_whitespace (const gchar *text)
return TRUE;
}
+/**
+ * seahorse_util_string_trim_whitespace:
+ * @text: The text to trim (UTF8)
+ *
+ * Whitespaces will be removed from the start and the end of the text.
+ */
void
seahorse_util_string_trim_whitespace (gchar *text)
{
@@ -1250,6 +1521,16 @@ seahorse_util_string_trim_whitespace (gchar *text)
g_memmove (text, b, (e + 1) - b);
}
+/**
+ * seahorse_util_hex_encode:
+ * @value: a buffer containing data
+ * @length: The length of this buffer
+ *
+ * Creates a string contining the @value in hex for printing.
+ *
+ * Returns: The hex encoded @value. The returned string should be freed
+ * with #g_free when no longer needed.
+ */
gchar*
seahorse_util_hex_encode (gconstpointer value, gsize length)
{
@@ -1267,7 +1548,18 @@ seahorse_util_hex_encode (gconstpointer value, gsize length)
return g_string_free (result, FALSE);
}
-/* Callback to determine where a popup menu should be placed */
+/**
+ * seahorse_util_determine_popup_menu_position:
+ * @menu: The menu to place
+ * @x: (out) x pos of the menu
+ * @y: (out) y pos of the menu
+ * @push_in: (out) will be set to TRUE
+ * @gdata: GTK_WIDGET for which the menu is
+ *
+ *
+ * Callback to determine where a popup menu should be placed
+ *
+ */
void
seahorse_util_determine_popup_menu_position (GtkMenu *menu, int *x, int *y,
gboolean *push_in, gpointer gdata)
diff --git a/libseahorse/seahorse-validity.c b/libseahorse/seahorse-validity.c
index 995df52..bf9ed90 100644
--- a/libseahorse/seahorse-validity.c
+++ b/libseahorse/seahorse-validity.c
@@ -26,6 +26,12 @@
#include "seahorse-validity.h"
+/**
+ * seahorse_validity_get_string:
+ * @validity: The validity ID
+ *
+ * Returns: A string describing the validity. Must not be freed
+ */
const gchar*
seahorse_validity_get_string (SeahorseValidity validity)
{
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
