Update API documentation.

Also, start fixing some Gtk-Doc warnings.  There's a lot.

27 files changed, 176 insertions, 98 deletions

diff --git a/doc/reference/shell/Makefile.am b/doc/reference/shell/Makefile.am
index f15d4b9c18..97322a1c40 100644
--- a/doc/reference/shell/Makefile.am
+++ b/doc/reference/shell/Makefile.am
@@ -8,7 +8,7 @@ DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
 # gtk-doc will search all .c & .h files beneath here for inline comments
 # documenting the functions and macros.
 # e.g. DOC_SOURCE_DIR=../../../gtk
-DOC_SOURCE_DIR=../../../
+DOC_SOURCE_DIR=../../..
 
 # Extra options to pass to gtkdoc-scangobj. Not normally needed.
 SCANGOBJ_OPTIONS=
diff --git a/doc/reference/shell/eshell-docs.sgml b/doc/reference/shell/eshell-docs.sgml
index b744d9c78a..99948f5007 100644
--- a/doc/reference/shell/eshell-docs.sgml
+++ b/doc/reference/shell/eshell-docs.sgml
@@ -6,8 +6,7 @@
     <title>Evolution Shell Reference Manual</title>
     <releaseinfo>
       The latest version of this documentation can be found on-line at
-      <ulink role="online-location"
-url="http://mbarnes.fedorapeople.org/docs/eshell/">http://mbarnes.fedorapeople.org/docs/eshell/</ulink>.
+      <ulink role="online-location" url="http://library.gnome.org/devel/eshell/unstable/">http://library.gnome.org/devel/eshell/unstable/</ulink>.
     </releaseinfo>
   </bookinfo>
 
diff --git a/doc/reference/shell/eshell-sections.txt b/doc/reference/shell/eshell-sections.txt
index f65ce604a2..2ae9b9153a 100644
--- a/doc/reference/shell/eshell-sections.txt
+++ b/doc/reference/shell/eshell-sections.txt
@@ -100,6 +100,8 @@ e_shell_searchbar_get_shell_view
 e_shell_searchbar_get_filter_combo_box
 e_shell_searchbar_get_filter_visible
 e_shell_searchbar_set_filter_visible
+e_shell_searchbar_get_label_visible
+e_shell_searchbar_set_label_visible
 e_shell_searchbar_get_search_hint
 e_shell_searchbar_set_search_hint
 e_shell_searchbar_get_search_option
@@ -111,7 +113,11 @@ e_shell_searchbar_set_search_visible
 e_shell_searchbar_get_scope_combo_box
 e_shell_searchbar_get_scope_visible
 e_shell_searchbar_set_scope_visible
-e_shell_searchbar_restore_state
+e_shell_searchbar_set_state_dirty
+e_shell_searchbar_get_state_group
+e_shell_searchbar_set_state_group
+e_shell_searchbar_load_state
+e_shell_searchbar_save_state
 <SUBSECTION Standard>
 E_SHELL_SEARCHBAR
 E_IS_SHELL_SEARCHBAR
@@ -292,6 +298,7 @@ e_shell_window_get_shell
 e_shell_window_get_shell_view
 e_shell_window_peek_shell_view
 e_shell_window_get_shell_view_action
+e_shell_window_get_focus_tracker
 e_shell_window_get_ui_manager
 e_shell_window_get_action
 e_shell_window_get_action_group
diff --git a/doc/reference/shell/tmpl/e-shell-searchbar.sgml b/doc/reference/shell/tmpl/e-shell-searchbar.sgml
index 3c55a58f6d..71f8894845 100644
--- a/doc/reference/shell/tmpl/e-shell-searchbar.sgml
+++ b/doc/reference/shell/tmpl/e-shell-searchbar.sgml
@@ -123,6 +123,24 @@ EShellSearchbar
 @filter_visible: 
 
 
+<!-- ##### FUNCTION e_shell_searchbar_get_label_visible ##### -->
+<para>
+
+</para>
+
+@searchbar: 
+@Returns: 
+
+
+<!-- ##### FUNCTION e_shell_searchbar_set_label_visible ##### -->
+<para>
+
+</para>
+
+@searchbar: 
+@label_visible: 
+
+
 <!-- ##### FUNCTION e_shell_searchbar_get_search_hint ##### -->
 <para>
 
@@ -222,3 +240,45 @@ EShellSearchbar
 @scope_visible: 
 
 
+<!-- ##### FUNCTION e_shell_searchbar_set_state_dirty ##### -->
+<para>
+
+</para>
+
+@searchbar: 
+
+
+<!-- ##### FUNCTION e_shell_searchbar_get_state_group ##### -->
+<para>
+
+</para>
+
+@searchbar: 
+@Returns: 
+
+
+<!-- ##### FUNCTION e_shell_searchbar_set_state_group ##### -->
+<para>
+
+</para>
+
+@searchbar: 
+@state_group: 
+
+
+<!-- ##### FUNCTION e_shell_searchbar_load_state ##### -->
+<para>
+
+</para>
+
+@searchbar: 
+
+
+<!-- ##### FUNCTION e_shell_searchbar_save_state ##### -->
+<para>
+
+</para>
+
+@searchbar: 
+
+
diff --git a/doc/reference/shell/tmpl/e-shell-window.sgml b/doc/reference/shell/tmpl/e-shell-window.sgml
index 383c782da2..0dcb1c4b5f 100644
--- a/doc/reference/shell/tmpl/e-shell-window.sgml
+++ b/doc/reference/shell/tmpl/e-shell-window.sgml
@@ -131,6 +131,15 @@ EShellWindow
 @Returns: 
 
 
+<!-- ##### FUNCTION e_shell_window_get_focus_tracker ##### -->
+<para>
+
+</para>
+
+@shell_window: 
+@Returns: 
+
+
 <!-- ##### FUNCTION e_shell_window_get_ui_manager ##### -->
 <para>
 
diff --git a/doc/reference/shell/tmpl/e-util.sgml b/doc/reference/shell/tmpl/e-util.sgml
index b94e7e8b41..72bf737586 100644
--- a/doc/reference/shell/tmpl/e-util.sgml
+++ b/doc/reference/shell/tmpl/e-util.sgml
@@ -1,5 +1,5 @@
 <!-- ##### SECTION Title ##### -->
-Miscellaneous Utility Functions
+Miscellaneous Utilities
 
 <!-- ##### SECTION Short_Description ##### -->
 
@@ -122,7 +122,7 @@ Miscellaneous Utility Functions
 
 </para>
 
-@s: 
+@string: 
 @Returns: 
 
 
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,
diff --git a/shell/e-shell-content.c b/shell/e-shell-content.c
index af318b8582..e0102908de 100644
--- a/shell/e-shell-content.c
+++ b/shell/e-shell-content.c
@@ -401,7 +401,7 @@ e_shell_content_new (EShellView *shell_view)
 
 /**
  * e_shell_content_get_searchbar:
- * @shell_view: an #EShellView
+ * @shell_content: an #EShellContent
  *
  * Returns the search bar widget returned by the
  * <structfield>construct_searchbar</structfield> method in
diff --git a/shell/e-shell-view.h b/shell/e-shell-view.h
index 60f3fcbdd2..d014d694ce 100644
--- a/shell/e-shell-view.h
+++ b/shell/e-shell-view.h
@@ -118,6 +118,10 @@ struct _EShellView {
  * @toggled:		Class method for the #EShellView::toggled signal.
  *			Subclasses should rarely need to override the
  *			default behavior.
+ * @clear_search:	Class method for the #EShellView::clear-search
+ *			signal.  The default method sets the
+ *			#EShellView:search-rule to %NULL and then emits
+ *			the #EShellView::execute-search signal.
  * @custom_search:	Class method for the #EShellView::custom-search
  *			signal.  This is emitted prior to executing an
  *			advanced or saved search.  The default method sets