diff options
Diffstat (limited to 'e-util')
| -rw-r--r-- | e-util/e-alert.c | 2 | ||||
| -rw-r--r-- | e-util/e-binding.c | 4 | ||||
| -rw-r--r-- | e-util/e-categories-config.c | 4 | ||||
| -rw-r--r-- | e-util/e-config.c | 13 | ||||
| -rw-r--r-- | e-util/e-config.h | 4 | ||||
| -rw-r--r-- | e-util/e-event.c | 4 | ||||
| -rw-r--r-- | e-util/e-file-utils.c | 4 | ||||
| -rw-r--r-- | e-util/e-html-utils.c | 2 | ||||
| -rw-r--r-- | e-util/e-icon-factory.c | 21 | ||||
| -rw-r--r-- | e-util/e-import.c | 6 | ||||
| -rw-r--r-- | e-util/e-import.h | 6 | ||||
| -rw-r--r-- | e-util/e-plugin-util.c | 23 | ||||
| -rw-r--r-- | e-util/e-plugin.c | 8 | ||||
| -rw-r--r-- | e-util/e-profile-event.c | 11 | ||||
| -rw-r--r-- | e-util/e-signature-list.c | 28 | ||||
| -rw-r--r-- | e-util/e-signature.c | 4 | ||||
| -rw-r--r-- | e-util/e-unicode.c | 10 | ||||
| -rw-r--r-- | e-util/e-util.c | 25 | ||||
| -rw-r--r-- | e-util/e-util.h | 2 |
19 files changed, 90 insertions, 91 deletions
diff --git a/e-util/e-alert.c b/e-util/e-alert.c index 20ab3221ec..ac9d9652bf 100644 --- a/e-util/e-alert.c +++ b/e-util/e-alert.c @@ -495,6 +495,8 @@ e_alert_init (EAlert *self) * which alert to use, it is in the format domain:alert-id. The NULL * terminated list of arguments, starting with @arg0 is used to fill * out the alert definition. + * + * Returns: a new #EAlert **/ EAlert * e_alert_new(const gchar *tag, const gchar *arg0, ...) diff --git a/e-util/e-binding.c b/e-util/e-binding.c index a2c37fff71..86362a7eff 100644 --- a/e-util/e-binding.c +++ b/e-util/e-binding.c @@ -310,8 +310,8 @@ e_binding_new_full (gpointer src_object, * * Convenience function for binding with boolean negation of value. * - * Return: The descriptor of the binding. It is automatically - * removed if one of the objects is finalized. + * Returns: The descriptor of the binding. It is automatically + * removed if one of the objects is finalized. **/ EBinding * e_binding_new_with_negation (gpointer src_object, diff --git a/e-util/e-categories-config.c b/e-util/e-categories-config.c index 1abef79983..fb2dc165b8 100644 --- a/e-util/e-categories-config.c +++ b/e-util/e-categories-config.c @@ -54,6 +54,8 @@ free_pixbuf_cb (gpointer ptr) * @pixbuf: A pointer to where the pixbuf will be returned. * * Returns the icon configured for the given category. + * + * Returns: the icon configured for the given category */ gboolean e_categories_config_get_icon_for (const gchar *category, GdkPixbuf **pixbuf) @@ -93,7 +95,7 @@ e_categories_config_get_icon_for (const gchar *category, GdkPixbuf **pixbuf) /** * e_categories_config_open_dialog_for_entry: - * entry: A GtkEntry on which to get/set the categories list. + * @entry: a #GtkEntry on which to get/set the categories list * * This is a self-contained function that lets you open a popup dialog for * the user to select a list of categories. diff --git a/e-util/e-config.c b/e-util/e-config.c index dea0f52284..613971fba5 100644 --- a/e-util/e-config.c +++ b/e-util/e-config.c @@ -1118,8 +1118,8 @@ ec_idle_handler_for_rebuild (gpointer data) /** * e_config_target_changed: - * @emp: - * @how: + * @emp: an #EConfig + * @how: an enum value indicating how the target has changed * * Indicate that the target has changed. This may be called by the * self-aware target itself, or by the driving code. If @how is @@ -1129,7 +1129,8 @@ ec_idle_handler_for_rebuild (gpointer data) * This is used to sensitise Assistant next/back buttons and the Apply * button for the Notebook mode. **/ -void e_config_target_changed(EConfig *emp, e_config_target_change_t how) +void +e_config_target_changed(EConfig *emp, e_config_target_change_t how) { if (how == E_CONFIG_TARGET_CHANGED_REBUILD) { g_idle_add (ec_idle_handler_for_rebuild, emp); @@ -1142,7 +1143,7 @@ void e_config_target_changed(EConfig *emp, e_config_target_change_t how) /** * e_config_abort: - * @ec: + * @config: an #EConfig * * Signify that the stateful configuration changes must be discarded * to all listeners. This is used by self-driven assistant or notebook, or @@ -1171,7 +1172,7 @@ e_config_abort (EConfig *config) /** * e_config_commit: - * @ec: + * @ec: an #EConfig * * Signify that the stateful configuration changes should be saved. * This is used by the self-driven assistant or notebook, or may be used @@ -1305,7 +1306,7 @@ e_config_page_next(EConfig *ec, const gchar *pageid) /** * e_config_page_next: - * @ec: + * @ec: an #EConfig * @pageid: The path of the page item. * * Find the path of the previous visible page before @pageid. If @pageid diff --git a/e-util/e-config.h b/e-util/e-config.h index dbc0585d85..77215b0b1d 100644 --- a/e-util/e-config.h +++ b/e-util/e-config.h @@ -373,9 +373,7 @@ struct _EConfigHook { }; /** - * struct _EConfigHookClass - Abstract class for configuration window - * plugin hooks. - * + * EConfigHookClass: * @hook_class: Superclass. * @target_map: A table of EConfigHookTargetMap structures describing * the possible target types supported by this class. diff --git a/e-util/e-event.c b/e-util/e-event.c index c1902082bc..81b58e8a04 100644 --- a/e-util/e-event.c +++ b/e-util/e-event.c @@ -195,8 +195,8 @@ e_event_add_items (EEvent *event, /** * e_event_remove_items: - * @event: - * @handle: + * @event: an #EEvent + * @handle: an opaque key returned by e_event_add_items() * * Remove items previously added. They MUST have been previously * added, and may only be removed once. diff --git a/e-util/e-file-utils.c b/e-util/e-file-utils.c index 5c3aab4f1e..60db352f6d 100644 --- a/e-util/e-file-utils.c +++ b/e-util/e-file-utils.c @@ -212,7 +212,7 @@ e_file_replace_contents_finish (GFile *file, /** * e_fsutils_usage: - * @path: + * @path: a file path * * Calculate the amount of disk space used by a given path. * @@ -279,7 +279,7 @@ fail: /** * e_fsutils_avail: - * @path: + * @path: a file path * * Find the available disk space at the given path. * diff --git a/e-util/e-html-utils.c b/e-util/e-html-utils.c index 8e3b050f65..f6743b9f75 100644 --- a/e-util/e-html-utils.c +++ b/e-util/e-html-utils.c @@ -211,6 +211,8 @@ is_citation (const guchar *c, gboolean saw_citation) * * - E_TEXT_TO_HTML_CITE: quote the text with "> " at the start of each * line. + * + * Returns: a newly-allocated string containing HTML **/ gchar * e_text_to_html_full (const gchar *input, guint flags, guint32 color) diff --git a/e-util/e-icon-factory.c b/e-util/e-icon-factory.c index 4f4b8d3a40..61b0b6acf0 100644 --- a/e-util/e-icon-factory.c +++ b/e-util/e-icon-factory.c @@ -125,11 +125,13 @@ e_icon_factory_get_icon (const gchar *icon_name, /** * e_icon_factory_pixbuf_scale - * Scales pixbuf to desired size. - * @param pixbuf Pixbuf to be scaled. - * @param width Desired width, if less or equal to 0, then changed to 1. - * @param height Desired height, if less or equal to 0, then changed to 1. - * @return Scaled pixbuf. + * @pixbuf: a #GdkPixbuf + * @width: desired width, if less or equal to 0, then changed to 1 + * @height: desired height, if less or equal to 0, then changed to 1 + * + * Scales @pixbuf to desired size. + * + * Returns: a scaled #GdkPixbuf **/ GdkPixbuf * e_icon_factory_pixbuf_scale (GdkPixbuf *pixbuf, gint width, gint height) @@ -151,9 +153,12 @@ e_icon_factory_pixbuf_scale (GdkPixbuf *pixbuf, gint width, gint height) /** * e_icon_factory_create_thumbnail - * Creates system thumbnail for a file filename. - * @param filename The file name to create the thumbnail for. - * @return Path to system thumbnail of the file; NULL if couldn't create it. Free it with g_free. + * @filename: the file name to create the thumbnail for + * + * Creates system thumbnail for @filename. + * + * Returns: Path to system thumbnail of the file; %NULL if couldn't + * create it. Free it with g_free(). **/ gchar * e_icon_factory_create_thumbnail (const gchar *filename) diff --git a/e-util/e-import.c b/e-util/e-import.c index e0bd5c6085..4475344018 100644 --- a/e-util/e-import.c +++ b/e-util/e-import.c @@ -156,7 +156,7 @@ e_import_new (const gchar *id) * @im: Importer to use. * @status: Status callback, called with progress information. * @done: Complete callback, will always be called once complete. - * @data: + * @data: user data for callback functions * * Run the import function of the selected importer. Once the * importer has finished, it MUST call the e_import_complete () @@ -243,8 +243,8 @@ e_import_status (EImport *import, /** * e_import_get_importers: - * @emp: - * @target: + * @emp: an #EImport + * @target: an #EImportTarget * * Get a list of importers. If @target is supplied, then only * importers which support the type and location specified by the diff --git a/e-util/e-import.h b/e-util/e-import.h index 41524bdddb..affc364a4b 100644 --- a/e-util/e-import.h +++ b/e-util/e-import.h @@ -279,9 +279,7 @@ struct _EImportHook { }; /** - * struct _EImportHookClass - Abstract class for importuration window - * plugin hooks. - * + * EImportHookClass: * @hook_class: Superclass. * @target_map: A table of EImportHookTargetMap structures describing * the possible target types supported by this class. @@ -289,7 +287,7 @@ struct _EImportHook { * implementation drives. * * This is an abstract class defining the plugin hook point for - * importuration windows. + * import windows. * **/ struct _EImportHookClass { diff --git a/e-util/e-plugin-util.c b/e-util/e-plugin-util.c index 885d017e15..c40d67650b 100644 --- a/e-util/e-plugin-util.c +++ b/e-util/e-plugin-util.c @@ -53,6 +53,8 @@ epu_is_uri_proto (const gchar *uri, const gchar *protocol) * @protocol: protocol to check on, like "http", "https", ... * * Returns whether given source's uri is of the given protocol. + * + * Returns: whether given source's uri is of the given protocol. **/ gboolean e_plugin_util_is_source_proto (ESource *source, const gchar *protocol) @@ -60,7 +62,6 @@ e_plugin_util_is_source_proto (ESource *source, const gchar *protocol) gchar *uri; gboolean res; - g_return_val_if_fail (source != NULL, FALSE); g_return_val_if_fail (E_IS_SOURCE (source), FALSE); g_return_val_if_fail (protocol != NULL, FALSE); @@ -77,11 +78,12 @@ e_plugin_util_is_source_proto (ESource *source, const gchar *protocol) * @protocol: protocol to check on, like "http", "https", ... * * Returns whether given groups' base uri is of the given protocol. + * + * Returns: whether given groups' base uri is of the given protocol. **/ gboolean e_plugin_util_is_group_proto (ESourceGroup *group, const gchar *protocol) { - g_return_val_if_fail (group != NULL, FALSE); g_return_val_if_fail (E_IS_SOURCE_GROUP (group), FALSE); g_return_val_if_fail (protocol != NULL, FALSE); @@ -93,7 +95,8 @@ e_plugin_util_is_group_proto (ESourceGroup *group, const gchar *protocol) * @str: string to work with * * Replaces all '@' with '%40' in @str. - * Returns newly allocated string. + * + * Returns: a newly-allocated string **/ gchar * e_plugin_util_replace_at_sign (const gchar *str) @@ -124,6 +127,8 @@ e_plugin_util_replace_at_sign (const gchar *str) * * Returns uri encoded as string, without protocol part. * Returned pointer should be freed with g_free. + * + * Returns: uri encoded as string, without protocol part. **/ gchar * e_plugin_util_uri_no_proto (SoupURI *uri) @@ -154,9 +159,7 @@ epu_update_source_property (ESource *source, GObject *object, const gchar *value { const gchar *property_name; - g_return_if_fail (source != NULL); g_return_if_fail (E_IS_SOURCE (source)); - g_return_if_fail (object != NULL); g_return_if_fail (G_IS_OBJECT (object)); property_name = g_object_get_data (object, EPU_SP_NAME); @@ -168,7 +171,6 @@ epu_update_source_property (ESource *source, GObject *object, const gchar *value static void epu_entry_changed_cb (GObject *entry, ESource *source) { - g_return_if_fail (entry != NULL); g_return_if_fail (GTK_IS_ENTRY (entry)); epu_update_source_property (source, entry, gtk_entry_get_text (GTK_ENTRY (entry))); @@ -179,7 +181,6 @@ epu_check_toggled_cb (GObject *button, ESource *source) { const gchar *true_value, *false_value; - g_return_if_fail (button != NULL); g_return_if_fail (GTK_IS_TOGGLE_BUTTON (button)); true_value = g_object_get_data (button, EPU_CHECK_TRUE); @@ -201,7 +202,7 @@ epu_check_toggled_cb (GObject *button, ESource *source) * source, and the source will be updated on any change of the entry automatically. * Entry is shown by default. * - * Returns pointer to newly added #GtkEntry. + * Returns: pointer to newly added #GtkEntry **/ GtkWidget * e_plugin_util_add_entry (GtkWidget *parent, const gchar *label, ESource *source, const gchar *source_property) @@ -214,7 +215,6 @@ e_plugin_util_add_entry (GtkWidget *parent, const gchar *label, ESource *source, g_return_val_if_fail (GTK_IS_TABLE (parent) || GTK_IS_CONTAINER (parent), NULL); if (source || source_property) { - g_return_val_if_fail (source != NULL, NULL); g_return_val_if_fail (E_IS_SOURCE (source), NULL); g_return_val_if_fail (source_property != NULL, NULL); g_return_val_if_fail (*source_property != 0, NULL); @@ -272,7 +272,7 @@ e_plugin_util_add_entry (GtkWidget *parent, const gchar *label, ESource *source, * source, and the source will be updated on any change of the check automatically. * Check is shown by default. * - * Returns pointer to newly added #GtkCheckButton. + * Returns: pointer to newly added #GtkCheckButton **/ GtkWidget * e_plugin_util_add_check (GtkWidget *parent, const gchar *label, ESource *source, const gchar *source_property, const gchar *true_value, const gchar *false_value) @@ -379,6 +379,8 @@ epu_refresh_combo_changed_cb (GtkWidget *combobox, ESource *source) * Adds widgets to setup Refresh interval. The stored value is in minutes. * Returns pointer to an HBox, which contains two widgets, spin and a combo box. * Both can be accessed by g_object_get_data with a name "refresh-spin" and "refresh-combo". + * + * Returns: a new refresh control widget **/ GtkWidget * e_plugin_util_add_refresh (GtkWidget *parent, const gchar *label, ESource *source, const gchar *source_property) @@ -388,7 +390,6 @@ e_plugin_util_add_refresh (GtkWidget *parent, const gchar *label, ESource *sourc gint row = -1, value_num, item_num = 0; g_return_val_if_fail (parent == NULL || GTK_IS_TABLE (parent), NULL); - g_return_val_if_fail (source != NULL, NULL); g_return_val_if_fail (E_IS_SOURCE (source), NULL); g_return_val_if_fail (source_property != NULL, NULL); g_return_val_if_fail (*source_property != 0, NULL); diff --git a/e-util/e-plugin.c b/e-util/e-plugin.c index 26cf35c126..453fdea643 100644 --- a/e-util/e-plugin.c +++ b/e-util/e-plugin.c @@ -641,7 +641,7 @@ e_plugin_list_plugins(void) /** * e_plugin_construct: - * @ep: An EPlugin derived object. + * @ep: an #EPlugin * @root: The XML root node of the sub-tree containing the plugin * definition. * @@ -664,7 +664,7 @@ e_plugin_construct(EPlugin *ep, xmlNodePtr root) /** * e_plugin_invoke: - * @ep: + * @ep: an #EPlugin * @name: The name of the function to invoke. The format of this name * will depend on the EPlugin type and its language conventions. * @data: The argument to the function. Its actual type depends on @@ -717,8 +717,8 @@ e_plugin_get_symbol(EPlugin *ep, const gchar *name) /** * e_plugin_enable: - * @ep: - * @state: + * @ep: an #EPlugin + * @state: %TRUE to enable, %FALSE to disable * * Set the enable state of a plugin. * diff --git a/e-util/e-profile-event.c b/e-util/e-profile-event.c index 4134ea95e4..33d7dfbdf7 100644 --- a/e-util/e-profile-event.c +++ b/e-util/e-profile-event.c @@ -89,15 +89,8 @@ e_profile_event_get_type(void) return type; } -/** - * e_profile_event_peek: - * @void: - * - * Get the singular instance of the profile event handler. - * - * Return value: - **/ -EProfileEvent *e_profile_event_peek(void) +EProfileEvent * +e_profile_event_peek(void) { if (e_profile_event == NULL) { e_profile_event = g_object_new(e_profile_event_get_type(), NULL); diff --git a/e-util/e-signature-list.c b/e-util/e-signature-list.c index 79ebb0be46..449d2bbd9d 100644 --- a/e-util/e-signature-list.c +++ b/e-util/e-signature-list.c @@ -376,36 +376,36 @@ e_signature_list_save (ESignatureList *signature_list) /** * e_signature_list_add: - * @signatures: signature list + * @signature_list: signature list * @signature: signature to add * * Add an signature to the signature list. Will emit the signature-changed * event. **/ void -e_signature_list_add (ESignatureList *signatures, ESignature *signature) +e_signature_list_add (ESignatureList *signature_list, ESignature *signature) { - e_list_append ((EList *) signatures, signature); - g_signal_emit (signatures, signals[SIGNATURE_ADDED], 0, signature); + e_list_append ((EList *) signature_list, signature); + g_signal_emit (signature_list, signals[SIGNATURE_ADDED], 0, signature); } /** * e_signature_list_change: - * @signatures: signature list + * @signature_list: signature list * @signature: signature to change * * Signal that the details of an signature have changed. **/ void -e_signature_list_change (ESignatureList *signatures, ESignature *signature) +e_signature_list_change (ESignatureList *signature_list, ESignature *signature) { /* maybe the signature should do this itself ... */ - g_signal_emit (signatures, signals[SIGNATURE_CHANGED], 0, signature); + g_signal_emit (signature_list, signals[SIGNATURE_CHANGED], 0, signature); } /** * e_signature_list_remove: - * @signatures: signature list + * @signature_list: signature list * @signature: signature * * Remove an signature from the signature list, and emit the @@ -413,18 +413,18 @@ e_signature_list_change (ESignatureList *signatures, ESignature *signature) * then reset the default to the first signature. **/ void -e_signature_list_remove (ESignatureList *signatures, ESignature *signature) +e_signature_list_remove (ESignatureList *signature_list, ESignature *signature) { /* not sure if need to ref but no harm */ g_object_ref (signature); - e_list_remove ((EList *) signatures, signature); - g_signal_emit (signatures, signals[SIGNATURE_REMOVED], 0, signature); + e_list_remove ((EList *) signature_list, signature); + g_signal_emit (signature_list, signals[SIGNATURE_REMOVED], 0, signature); g_object_unref (signature); } /** * e_signature_list_find: - * @signatures: signature list + * @signature_list: signature list * @type: Type of search. * @key: Search key. * @@ -437,7 +437,7 @@ e_signature_list_remove (ESignatureList *signatures, ESignature *signature) * Return value: The signature or NULL if it doesn't exist. **/ const ESignature * -e_signature_list_find (ESignatureList *signatures, +e_signature_list_find (ESignatureList *signature_list, e_signature_find_t type, const gchar *key) { @@ -450,7 +450,7 @@ e_signature_list_find (ESignatureList *signatures, if (!key) return NULL; - for (it = e_list_get_iterator ((EList *) signatures); + for (it = e_list_get_iterator ((EList *) signature_list); e_iterator_is_valid (it); e_iterator_next (it)) { const gchar *value = NULL; diff --git a/e-util/e-signature.c b/e-util/e-signature.c index ea6636c055..c4ae7ed69d 100644 --- a/e-util/e-signature.c +++ b/e-util/e-signature.c @@ -354,6 +354,8 @@ e_signature_get_type (void) * * Returns a new signature which can be filled in and * added to an #ESignatureList. + * + * Returns: a new #ESignature **/ ESignature * e_signature_new (void) @@ -425,7 +427,7 @@ e_signature_uid_from_xml (const gchar *xml) * * Changes @signature to match @xml. * - * Returns %TRUE if the signature was loaded or %FALSE otherwise. + * Returns: %TRUE if the signature was loaded or %FALSE otherwise **/ gboolean e_signature_set_from_xml (ESignature *signature, const gchar *xml) diff --git a/e-util/e-unicode.c b/e-util/e-unicode.c index 2e8969f718..aa1281fc3b 100644 --- a/e-util/e-unicode.c +++ b/e-util/e-unicode.c @@ -212,12 +212,14 @@ e_utf8_from_locale_string_sized (const gchar *string, gint bytes) /** * e_utf8_ensure_valid: - * @string String to make valid UTF-8. + * @string: string to make valid UTF-8 * - * Ensures the returned string will be valid UTF-8 string, thus gtk functions expecting - * only valid UTF-8 texts will not crash. + * Ensures the returned string will be valid UTF-8 string, thus GTK+ + * functions expecting only valid UTF-8 text will not crash. * - * Returned pointer should be freed with g_free. + * Returned pointer should be freed with g_free(). + * + * Returns: a newly-allocated UTF-8 string **/ gchar * e_utf8_ensure_valid (const gchar *string) diff --git a/e-util/e-util.c b/e-util/e-util.c index eaf98f33e5..202c956dc1 100644 --- a/e-util/e-util.c +++ b/e-util/e-util.c @@ -650,7 +650,7 @@ e_int_compare (gconstpointer x, gconstpointer y) /** * e_color_to_value: - * color: a #GdkColor + * @color: a #GdkColor * * Converts a #GdkColor to a 24-bit RGB color value. * @@ -817,8 +817,7 @@ e_bsearch (gconstpointer key, *end = l; } -/** - * Function to do a last minute fixup of the AM/PM stuff if the locale +/* Function to do a last minute fixup of the AM/PM stuff if the locale * and gettext haven't done it right. Most English speaking countries * except the USA use the 24 hour clock (UK, Australia etc). However * since they are English nobody bothers to write a language @@ -833,7 +832,7 @@ e_bsearch (gconstpointer key, * * TODO: Actually remove the '%p' from the fixed up string so that * there isn't a stray space. - **/ + */ gsize e_strftime_fix_am_pm (gchar *str, gsize max, const gchar *fmt, @@ -852,22 +851,16 @@ e_strftime_fix_am_pm (gchar *str, gsize max, const gchar *fmt, e_strftime (buf, 10, "%p", tm); if (buf[0]) { - /** - * AM/PM have been defined in the locale - * so we can use the fmt string directly - **/ + /* AM/PM have been defined in the locale + * so we can use the fmt string directly. */ ret=e_strftime(str, max, fmt, tm); } else { - /** - * No AM/PM defined by locale - * must change to 24 hour clock - **/ + /* No AM/PM defined by locale + * must change to 24 hour clock. */ ffmt=g_strdup(fmt); for (sp=ffmt; (sp=strstr(sp, "%l")); sp++) { - /** - * Maybe this should be 'k', but I have never - * seen a 24 clock actually use that format - **/ + /* Maybe this should be 'k', but I have never + * seen a 24 clock actually use that format. */ sp[1]='H'; } for (sp=ffmt; (sp=strstr(sp, "%I")); sp++) { diff --git a/e-util/e-util.h b/e-util/e-util.h index 276d20f310..45d3801453 100644 --- a/e-util/e-util.h +++ b/e-util/e-util.h @@ -79,7 +79,7 @@ void e_type_traverse (GType parent_type, ETypeFunc func, gpointer user_data); -gchar * e_str_without_underscores (const gchar *s); +gchar * e_str_without_underscores (const gchar *string); gint e_str_compare (gconstpointer x, gconstpointer y); gint e_str_case_compare (gconstpointer x, |