Continue documenting the new shell API.

svn path=/branches/kill-bonobo/; revision=36511

16 files changed, 504 insertions, 21 deletions

diff --git a/shell/e-shell-content.c b/shell/e-shell-content.c
index f3685793b7..d331e839c1 100644
--- a/shell/e-shell-content.c
+++ b/shell/e-shell-content.c
@@ -208,7 +208,6 @@ shell_content_init_search_context (EShellContent *shell_content)
 {
 	EShellView *shell_view;
 	EShellModule *shell_module;
-	EShellViewClass *shell_view_class;
 	RuleContext *context;
 	FilterRule *rule;
 	FilterPart *part;
@@ -216,8 +215,7 @@ shell_content_init_search_context (EShellContent *shell_content)
 	gchar *user_filename;
 
 	shell_view = e_shell_content_get_shell_view (shell_content);
-	shell_view_class = E_SHELL_VIEW_GET_CLASS (shell_view);
-	shell_module = E_SHELL_MODULE (shell_view_class->type_module);
+	shell_module = e_shell_view_get_shell_module (shell_view);
 
 	/* The filename for built-in searches is specified in a
 	 * module's EShellModuleInfo.  All built-in search rules
@@ -254,7 +252,7 @@ shell_content_init_search_context (EShellContent *shell_content)
 	if (part == NULL)
 		g_warning (
 			"Could not load %s search: no parts",
-			shell_view_class->type_module->name);
+			e_shell_view_get_name (shell_view));
 	else
 		filter_rule_add_part (rule, filter_part_clone (part));
 
diff --git a/shell/e-shell-content.h b/shell/e-shell-content.h
index ae9d0446ab..eab7576af2 100644
--- a/shell/e-shell-content.h
+++ b/shell/e-shell-content.h
@@ -18,6 +18,12 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION: e-shell-content
+ * @short_description: the right side of the main window
+ * @include: shell/e-shell-content.h
+ **/
+
 #ifndef E_SHELL_CONTENT_H
 #define E_SHELL_CONTENT_H
 
@@ -53,6 +59,12 @@ typedef struct _EShellContent EShellContent;
 typedef struct _EShellContentClass EShellContentClass;
 typedef struct _EShellContentPrivate EShellContentPrivate;
 
+/**
+ * EShellContent:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ **/
 struct _EShellContent {
 	GtkBin parent;
 	EShellContentPrivate *priv;
diff --git a/shell/e-shell-module.c b/shell/e-shell-module.c
index 1fdee61426..6c7829f160 100644
--- a/shell/e-shell-module.c
+++ b/shell/e-shell-module.c
@@ -403,6 +403,18 @@ e_shell_module_get_filename (EShellModule *shell_module)
 	return shell_module->priv->filename;
 }
 
+/**
+ * e_shell_module_get_searches:
+ * @shell_module: an #EShellModule
+ *
+ * Returns the base name of the XML file containing predefined search
+ * rules for @shell_module.  The XML files are usually named something
+ * like <filename><emphasis>module</emphasis>types.xml</filename>.
+ *
+ * XXX This function is likely to change or disappear.
+ *
+ * Returns: the base name of the XML filter file
+ **/
 const gchar *
 e_shell_module_get_searches (EShellModule *shell_module)
 {
@@ -444,6 +456,21 @@ e_shell_module_add_activity (EShellModule *shell_module,
 	g_signal_emit (shell_module, signals[ACTIVITY_ADDED], 0, activity);
 }
 
+/**
+ * e_shell_module_is_busy:
+ * @shell_module: an #EShellModule
+ *
+ * Returns %TRUE if @shell_module is busy and cannot be shutdown at
+ * present.  Each module must define what "busy" means to them and
+ * determine an appropriate response.
+ *
+ * XXX This function is likely to change or disappear.  I'm toying with
+ *     the idea of just having it check whether there are any unfinished
+ *     #EActivity<!-- -->'s left, so we have a consistent and easily
+ *     testable definition of what "busy" means.
+ *
+ * Returns: %TRUE if the module is busy
+ **/
 gboolean
 e_shell_module_is_busy (EShellModule *shell_module)
 {
@@ -459,6 +486,22 @@ e_shell_module_is_busy (EShellModule *shell_module)
 	return FALSE;
 }
 
+/**
+ * e_shell_module_shutdown:
+ * @shell_module: an #EShellModule
+ *
+ * Alerts @shell_module to begin shutdown procedures.  If the module is
+ * busy and cannot immediately shut down, the function returns %FALSE.
+ * A %TRUE response implies @shell_module has successfully shut down.
+ *
+ * XXX This function is likely to change or disappear.  I'm toying with
+ *     the idea of just having it check whether there are any unfinished
+ *     #EActivity<!-- -->'s left, so we have a consistent and easily
+ *     testable definition of what "busy" means.
+ *
+ * Returns: %TRUE if the module has shut down, %FALSE if the module is
+ *          busy and cannot immediately shut down
+ */
 gboolean
 e_shell_module_shutdown (EShellModule *shell_module)
 {
diff --git a/shell/e-shell-module.h b/shell/e-shell-module.h
index b28b2f048a..4c4a45f957 100644
--- a/shell/e-shell-module.h
+++ b/shell/e-shell-module.h
@@ -18,6 +18,12 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION: e-shell-module
+ * @short_description: dynamically loaded capabilities
+ * @include: shell/e-shell-module.h
+ **/
+
 #ifndef E_SHELL_MODULE_H
 #define E_SHELL_MODULE_H
 
@@ -89,6 +95,12 @@ struct _EShellModuleInfo {
 	gboolean	(*shutdown)		(EShellModule *shell_module);
 };
 
+/**
+ * EShellModule:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ **/
 struct _EShellModule {
 	GTypeModule parent;
 	EShellModulePrivate *priv;
diff --git a/shell/e-shell-sidebar.h b/shell/e-shell-sidebar.h
index 7bc26e965b..b9463c2b13 100644
--- a/shell/e-shell-sidebar.h
+++ b/shell/e-shell-sidebar.h
@@ -18,6 +18,12 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION: e-shell-sidebar
+ * @short_description: the left side of the main window
+ * @include: shell/e-shell-sidebar.h
+ **/
+
 #ifndef E_SHELL_SIDEBAR_H
 #define E_SHELL_SIDEBAR_H
 
@@ -51,6 +57,12 @@ typedef struct _EShellSidebar EShellSidebar;
 typedef struct _EShellSidebarClass EShellSidebarClass;
 typedef struct _EShellSidebarPrivate EShellSidebarPrivate;
 
+/**
+ * EShellSidebar:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ **/
 struct _EShellSidebar {
 	GtkBin parent;
 	EShellSidebarPrivate *priv;
diff --git a/shell/e-shell-switcher.c b/shell/e-shell-switcher.c
index 2910e1d0a0..cbf283dc52 100644
--- a/shell/e-shell-switcher.c
+++ b/shell/e-shell-switcher.c
@@ -649,6 +649,18 @@ e_shell_switcher_unset_style (EShellSwitcher *switcher)
 	switcher->priv->style_set = FALSE;
 }
 
+/**
+ * e_shell_switcher_get_visible:
+ * @switcher: an #EShellSwitcher
+ *
+ * Returns %TRUE if the switcher buttons are visible.
+ *
+ * Note that switcher button visibility is different than
+ * @switcher<!-- -->'s GTK_VISIBLE flag, since #EShellSwitcher
+ * is actually a container widget for #EShellSidebar.
+ *
+ * Returns: %TRUE if the switcher buttons are visible
+ **/
 gboolean
 e_shell_switcher_get_visible (EShellSwitcher *switcher)
 {
@@ -657,6 +669,16 @@ e_shell_switcher_get_visible (EShellSwitcher *switcher)
 	return switcher->priv->toolbar_visible;
 }
 
+/**
+ * e_shell_switcher_set_visible:
+ * @switcher: an #EShellSwitcher
+ *
+ * Sets the switcher button visiblity to @visible.
+ *
+ * Note that switcher button visibility is different than
+ * @switcher<!-- -->'s GTK_VISIBLE flag, since #EShellSwitcher
+ * is actually a container widget for #EShellSidebar.
+ **/
 void
 e_shell_switcher_set_visible (EShellSwitcher *switcher,
                               gboolean visible)
diff --git a/shell/e-shell-switcher.h b/shell/e-shell-switcher.h
index 499372f81e..2fbd7e6dae 100644
--- a/shell/e-shell-switcher.h
+++ b/shell/e-shell-switcher.h
@@ -18,6 +18,12 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION: e-shell-switcher
+ * @short_description: buttons for switching views
+ * @include: shell/e-shell-switcher.h
+ **/
+
 #ifndef E_SHELL_SWITCHER_H
 #define E_SHELL_SWITCHER_H
 
@@ -50,6 +56,12 @@ typedef struct _EShellSwitcher EShellSwitcher;
 typedef struct _EShellSwitcherClass EShellSwitcherClass;
 typedef struct _EShellSwitcherPrivate EShellSwitcherPrivate;
 
+/**
+ * EShellSwitcher:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ **/
 struct _EShellSwitcher {
 	GtkBin parent;
 	EShellSwitcherPrivate *priv;
diff --git a/shell/e-shell-taskbar.c b/shell/e-shell-taskbar.c
index 3e5824f910..24ce2c9994 100644
--- a/shell/e-shell-taskbar.c
+++ b/shell/e-shell-taskbar.c
@@ -198,14 +198,12 @@ static void
 shell_taskbar_constructed (GObject *object)
 {
 	EShellView *shell_view;
-	EShellViewClass *shell_view_class;
-	EShellTaskbar *shell_taskbar;
 	EShellModule *shell_module;
+	EShellTaskbar *shell_taskbar;
 
 	shell_taskbar = E_SHELL_TASKBAR (object);
 	shell_view = e_shell_taskbar_get_shell_view (shell_taskbar);
-	shell_view_class = E_SHELL_VIEW_GET_CLASS (shell_view);
-	shell_module = E_SHELL_MODULE (shell_view_class->type_module);
+	shell_module = e_shell_view_get_shell_module (shell_view);
 
 	g_signal_connect_swapped (
 		shell_module, "activity-added",
diff --git a/shell/e-shell-taskbar.h b/shell/e-shell-taskbar.h
index 466750dd77..7cbab96a43 100644
--- a/shell/e-shell-taskbar.h
+++ b/shell/e-shell-taskbar.h
@@ -18,6 +18,12 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION: e-shell-taskbar
+ * @short_description: the bottom of the main window
+ * @include: shell/e-shell-taskbar.h
+ **/
+
 #ifndef E_SHELL_TASKBAR_H
 #define E_SHELL_TASKBAR_H
 
@@ -51,6 +57,12 @@ typedef struct _EShellTaskbar EShellTaskbar;
 typedef struct _EShellTaskbarClass EShellTaskbarClass;
 typedef struct _EShellTaskbarPrivate EShellTaskbarPrivate;
 
+/**
+ * EShellTaskbar:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ **/
 struct _EShellTaskbar {
 	GtkHBox parent;
 	EShellTaskbarPrivate *priv;
diff --git a/shell/e-shell-view.c b/shell/e-shell-view.c
index ab1039b0e5..9273376f2d 100644
--- a/shell/e-shell-view.c
+++ b/shell/e-shell-view.c
@@ -458,7 +458,7 @@ shell_view_class_init (EShellViewClass *class)
 		g_param_spec_string (
 			"view-id",
 			_("Current View ID"),
-			_("The current view ID"),
+			_("The current GAL view ID"),
 			NULL,
 			G_PARAM_READWRITE));
 
@@ -602,6 +602,22 @@ e_shell_view_get_shell_window (EShellView *shell_view)
 	return E_SHELL_WINDOW (shell_view->priv->shell_window);
 }
 
+EShellModule *
+e_shell_view_get_shell_module (EShellView *shell_view)
+{
+	EShellViewClass *shell_view_class;
+
+	g_return_val_if_fail (E_IS_SHELL_VIEW (shell_view), NULL);
+
+	/* Calling this function during the shell view's instance
+	 * initialization function will return the wrong result,
+	 * so catch that and emit a warning. */
+	shell_view_class = E_SHELL_VIEW_GET_CLASS (shell_view);
+	g_return_val_if_fail (E_IS_SHELL_VIEW_CLASS (shell_view_class), NULL);
+
+	return E_SHELL_MODULE (shell_view_class->type_module);
+}
+
 gboolean
 e_shell_view_is_active (EShellView *shell_view)
 {
@@ -618,14 +634,12 @@ void
 e_shell_view_add_activity (EShellView *shell_view,
                            EActivity *activity)
 {
-	EShellViewClass *shell_view_class;
 	EShellModule *shell_module;
 
 	g_return_if_fail (E_IS_SHELL_VIEW (shell_view));
 	g_return_if_fail (E_IS_ACTIVITY (activity));
 
-	shell_view_class = E_SHELL_VIEW_GET_CLASS (shell_view);
-	shell_module = E_SHELL_MODULE (shell_view_class->type_module);
+	shell_module = e_shell_view_get_shell_module (shell_view);
 	e_shell_module_add_activity (shell_module, activity);
 }
 
diff --git a/shell/e-shell-view.h b/shell/e-shell-view.h
index 7998326329..f9f027d0bb 100644
--- a/shell/e-shell-view.h
+++ b/shell/e-shell-view.h
@@ -19,11 +19,18 @@
  * Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION: e-shell-view
+ * @short_description: views within the main window
+ * @include: shell/e-shell-view.h
+ **/
+
 #ifndef E_SHELL_VIEW_H
 #define E_SHELL_VIEW_H
 
 #include <shell/e-shell-common.h>
 #include <shell/e-shell-content.h>
+#include <shell/e-shell-module.h>
 #include <shell/e-shell-sidebar.h>
 #include <shell/e-shell-taskbar.h>
 #include <shell/e-shell-window.h>
@@ -56,6 +63,12 @@ typedef struct _EShellView EShellView;
 typedef struct _EShellViewClass EShellViewClass;
 typedef struct _EShellViewPrivate EShellViewPrivate;
 
+/**
+ * EShellView:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ **/
 struct _EShellView {
 	GObject parent;
 	EShellViewPrivate *priv;
@@ -71,7 +84,7 @@ struct _EShellViewClass {
 	/* Base name of the UI definition file. */
 	const gchar *ui_definition;
 
-	/* Path to the search entry popup menu. */
+	/* Widget path to the search entry popup menu. */
 	const gchar *search_options;
 
 	/* Subclasses should set this via the "class_data" field in
@@ -109,6 +122,7 @@ EShellContent *	e_shell_view_get_shell_content	(EShellView *shell_view);
 EShellSidebar *	e_shell_view_get_shell_sidebar	(EShellView *shell_view);
 EShellTaskbar *	e_shell_view_get_shell_taskbar	(EShellView *shell_view);
 EShellWindow *	e_shell_view_get_shell_window	(EShellView *shell_view);
+EShellModule *	e_shell_view_get_shell_module	(EShellView *shell_view);
 void		e_shell_view_update_actions	(EShellView *shell_view);
 void		e_shell_view_show_popup_menu	(EShellView *shell_view,
 						 const gchar *widget_path,
diff --git a/shell/e-shell-window-actions.c b/shell/e-shell-window-actions.c
index ab403c31dc..c13204942e 100644
--- a/shell/e-shell-window-actions.c
+++ b/shell/e-shell-window-actions.c
@@ -40,12 +40,12 @@
 
 /* Authors and Documenters
  *
- * The names below must be in UTF8.  The breaking of escaped strings
+ * The names below must be in UTF-8.  The breaking of escaped strings
  * is so the hexadecimal sequences don't swallow too many characters.
  *
  * SO THAT MEANS, FOR 8-BIT CHARACTERS USE \xXX HEX ENCODING ONLY!
  *
- * Not all environments are UTF8 and not all editors can handle it.
+ * Not all environments are UTF-8 and not all editors can handle it.
  */
 static const gchar *authors[] = {
 	"Aaron Weber",
@@ -623,6 +623,14 @@ static const gchar *documenters[] = {
 	NULL
 };
 
+/**
+ * E_SHELL_WINDOW_ACTION_ABOUT:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action displays the application's About dialog.
+ *
+ * Main menu item: Help -> About
+ **/
 static void
 action_about_cb (GtkAction *action,
                  EShellWindow *shell_window)
@@ -651,6 +659,15 @@ action_about_cb (GtkAction *action,
 		NULL);
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_CLOSE:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action closes @window.  If this is the last window,
+ * the application initiates shutdown.
+ *
+ * Main menu item: File -> Close
+ **/
 static void
 action_close_cb (GtkAction *action,
                  EShellWindow *shell_window)
@@ -666,6 +683,14 @@ action_close_cb (GtkAction *action,
 	gdk_event_free (event);
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_CONTENTS:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action opens the application's user manual.
+ *
+ * Main menu item: Help -> Contents
+ **/
 static void
 action_contents_cb (GtkAction *action,
                     EShellWindow *shell_window)
@@ -696,6 +721,15 @@ action_custom_rule_cb (GtkAction *action,
 	gtk_action_activate (ACTION (SEARCH_EXECUTE));
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_FAQ:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action opens a web page with answers to frequently
+ * asked questions about this application.
+ *
+ * Main menu item: Help -> Evolution FAQ
+ **/
 static void
 action_faq_cb (GtkAction *action,
                EShellWindow *shell_window)
@@ -711,6 +745,14 @@ action_faq_cb (GtkAction *action,
 	}
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_FORGET_PASSWORDS:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action deletes all stored passwords.
+ *
+ * Main menu item: File -> Forget Passwords
+ **/
 static void
 action_forget_passwords_cb (GtkAction *action,
                             EShellWindow *shell_window)
@@ -724,6 +766,15 @@ action_forget_passwords_cb (GtkAction *action,
 		e_passwords_forget_passwords ();
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_GAL_DEFINE_VIEWS:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action opens a dialog for editing GAL views for
+ * the current shell view.
+ *
+ * Main menu item: View -> Current View -> Define Views...
+ **/
 static void
 action_gal_define_views_cb (GtkAction *action,
                             EShellWindow *shell_window)
@@ -748,6 +799,15 @@ action_gal_define_views_cb (GtkAction *action,
 	e_shell_window_update_view_menu (shell_window);
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_GAL_CUSTOM_VIEW:
+ * @window: an #EShellWindow
+ *
+ * This radio action is selected when using a custom GAL view that has
+ * not been saved.
+ *
+ * Main menu item: View -> Current View -> Custom View
+ **/
 static void
 action_gal_view_cb (GtkRadioAction *action,
                     GtkRadioAction *current,
@@ -763,6 +823,23 @@ action_gal_view_cb (GtkRadioAction *action,
 	e_shell_view_set_view_id (shell_view, view_id);
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_GAL_SAVE_CUSTOM_VIEW:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action saves a custom GAL view.
+ *
+ * Main menu item: View -> Current View -> Save Custom View...
+ **/
+
+/**
+ * E_SHELL_WINDOW_ACTION_IMPORT:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action opens the Evolution Import Assistant.
+ *
+ * Main menu item: File -> Import...
+ **/
 static void
 action_import_cb (GtkAction *action,
                   EShellWindow *shell_window)
@@ -770,6 +847,14 @@ action_import_cb (GtkAction *action,
 	e_shell_importer_start_import (shell_window);
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_NEW_WINDOW:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action opens a new shell window.
+ *
+ * Main menu item: File -> New Window
+ **/
 static void
 action_new_window_cb (GtkAction *action,
                       EShellWindow *shell_window)
@@ -780,6 +865,14 @@ action_new_window_cb (GtkAction *action,
 	e_shell_create_window (shell);
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_PAGE_SETUP:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action opens the application's Page Setup dialog.
+ *
+ * Main menu item: File -> Page Setup...
+ **/
 static void
 action_page_setup_cb (GtkAction *action,
                       EShellWindow *shell_window)
@@ -787,6 +880,14 @@ action_page_setup_cb (GtkAction *action,
 	e_print_run_page_setup_dialog (GTK_WINDOW (shell_window));
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_PREFERENCES:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action opens the application's Preferences window.
+ *
+ * Main menu item: Edit -> Preferences
+ **/
 static void
 action_preferences_cb (GtkAction *action,
                        EShellWindow *shell_window)
@@ -805,6 +906,15 @@ action_preferences_cb (GtkAction *action,
 	/* FIXME Switch to a page appropriate for the current view. */
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_QUICK_REFERENCE:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action opens a printable table of useful shortcut
+ * keys for this application.
+ *
+ * Main menu item: Help -> Quick Reference
+ **/
 static void
 action_quick_reference_cb (GtkAction *action,
                            EShellWindow *shell_window)
@@ -850,6 +960,14 @@ action_quick_reference_cb (GtkAction *action,
 	}
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_QUIT:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action initiates application shutdown.
+ *
+ * Main menu item: File -> Quit
+ **/
 static void
 action_quit_cb (GtkAction *action,
                 EShellWindow *shell_window)
@@ -860,6 +978,14 @@ action_quit_cb (GtkAction *action,
 	e_shell_quit (shell);
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_SEARCH_ADVANCED:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action opens an Advanced Search dialog.
+ *
+ * Main menu item: Search -> Advanced Search...
+ **/
 static void
 action_search_advanced_cb (GtkAction *action,
                            EShellWindow *shell_window)
@@ -876,6 +1002,14 @@ action_search_advanced_cb (GtkAction *action,
 	e_shell_window_update_search_menu (shell_window);
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_SEARCH_CLEAR:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action clears the most recent search results.
+ *
+ * Main menu item: Search -> Clear
+ **/
 static void
 action_search_clear_cb (GtkAction *action,
                         EShellWindow *shell_window)
@@ -896,6 +1030,14 @@ action_search_clear_cb (GtkAction *action,
 	e_shell_window_update_search_menu (shell_window);
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_SEARCH_EDIT:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action opens a dialog for editing saved searches.
+ *
+ * Main menu item: Search -> Edit Saved Searches...
+ **/
 static void
 action_search_edit_cb (GtkAction *action,
                        EShellWindow *shell_window)
@@ -912,6 +1054,22 @@ action_search_edit_cb (GtkAction *action,
 	e_shell_window_update_search_menu (shell_window);
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_SEARCH_EXECUTE:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action executes the current search conditions.
+ *
+ * Main menu item: Search -> Find Now
+ **/
+
+/**
+ * E_SHELL_WINDOW_ACTION_SEARCH_OPTIONS:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action displays a menu of search options.
+ * This appears as a "find" icon in the window's search entry.
+ **/
 static void
 action_search_options_cb (GtkAction *action,
                           EShellWindow *shell_window)
@@ -929,6 +1087,14 @@ action_search_options_cb (GtkAction *action,
 	e_shell_view_show_popup_menu (shell_view, widget_path, NULL);
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_SEARCH_SAVE:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action saves the current search conditions.
+ *
+ * Main menu item: Search -> Save Search...
+ **/
 static void
 action_search_save_cb (GtkAction *action,
                        EShellWindow *shell_window)
@@ -945,6 +1111,14 @@ action_search_save_cb (GtkAction *action,
 	e_shell_window_update_search_menu (shell_window);
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_SEND_RECEIVE:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action opens the Send &amp; Receive Mail dialog.
+ *
+ * Main menu item: File -> Send / Receive
+ **/
 static void
 action_send_receive_cb (GtkAction *action,
                         EShellWindow *shell_window)
@@ -955,6 +1129,14 @@ action_send_receive_cb (GtkAction *action,
 	e_shell_send_receive (shell, GTK_WINDOW (shell_window));
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_SHOW_SIDEBAR:
+ * @window: an #EShellWindow
+ *
+ * This toggle action controls whether the side bar is visible.
+ *
+ * Main menu item: View -> Layout -> Show Side Bar
+ **/
 static void
 action_show_sidebar_cb (GtkToggleAction *action,
                         EShellWindow *shell_window)
@@ -970,6 +1152,14 @@ action_show_sidebar_cb (GtkToggleAction *action,
 	g_object_set (widget, "visible", active, NULL);
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_SHOW_STATUSBAR:
+ * @window: an #EShellWindow
+ *
+ * This toggle action controls whether the status bar is visible.
+ *
+ * Main menu item: View -> Layout -> Show Status Bar
+ **/
 static void
 action_show_statusbar_cb (GtkToggleAction *action,
                           EShellWindow *shell_window)
@@ -982,6 +1172,14 @@ action_show_statusbar_cb (GtkToggleAction *action,
 	g_object_set (widget, "visible", active, NULL);
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_SHOW_SWITCHER:
+ * @window: an #EShellWindow
+ *
+ * This toggle action controls whether the switcher buttons are visible.
+ *
+ * Main menu item: View -> Switcher Appearance -> Show Buttons
+ **/
 static void
 action_show_switcher_cb (GtkToggleAction *action,
                          EShellWindow *shell_window)
@@ -994,6 +1192,14 @@ action_show_switcher_cb (GtkToggleAction *action,
 	e_shell_switcher_set_visible (switcher, active);
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_SHOW_TOOLBAR:
+ * @window: an #EShellWindow
+ *
+ * This toggle action controls whether the tool bar is visible.
+ *
+ * Main menu item: View -> Layout -> Show Tool Bar
+ **/
 static void
 action_show_toolbar_cb (GtkToggleAction *action,
                         EShellWindow *shell_window)
@@ -1006,6 +1212,15 @@ action_show_toolbar_cb (GtkToggleAction *action,
 	g_object_set (widget, "visible", active, NULL);
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_SUBMIT_BUG:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action allows users to report a bug using
+ * Bug Buddy.
+ *
+ * Main menu item: Help -> Submit Bug Report
+ **/
 static void
 action_submit_bug_cb (GtkAction *action,
                       EShellWindow *shell_window)
@@ -1041,6 +1256,42 @@ action_switcher_cb (GtkRadioAction *action,
 	e_shell_window_switch_to_view (shell_window, view_name);
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_SWITCHER_STYLE_BOTH:
+ * @window: an #EShellWindow
+ *
+ * This radio action displays switcher buttons with icons and text.
+ *
+ * Main menu item: View -> Switcher Appearance -> Icons and Text
+ **/
+
+/**
+ * E_SHELL_WINDOW_ACTION_SWITCHER_STYLE_ICONS:
+ * @window: an #EShellWindow
+ *
+ * This radio action displays switcher buttons with icons only.
+ *
+ * Main menu item: View -> Switcher Appearance -> Icons Only
+ **/
+
+/**
+ * E_SHELL_WINDOW_ACTION_SWITCHER_STYLE_TEXT:
+ * @window: an #EShellWindow
+ *
+ * This radio action displays switcher buttons with text only.
+ *
+ * Main menu item: View -> Switcher Appearance -> Text Only
+ **/
+
+/**
+ * E_SHELL_WINDOW_ACTION_SWITCHER_STYLE_USER:
+ * @window: an #EShellWindow
+ *
+ * This radio action displays switcher buttons according to the desktop
+ * toolbar setting.
+ *
+ * Main menu item: View -> Switcher Appearance -> Toolbar Style
+ **/
 static void
 action_switcher_style_cb (GtkRadioAction *action,
                           GtkRadioAction *current,
@@ -1066,6 +1317,14 @@ action_switcher_style_cb (GtkRadioAction *action,
 	}
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_SYNC_OPTIONS:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action opens the Gnome Pilot settings.
+ *
+ * Main menu item: Edit -> Synchronization Options...
+ **/
 static void
 action_sync_options_cb (GtkAction *action,
                         EShellWindow *shell_window)
@@ -1090,6 +1349,14 @@ action_sync_options_cb (GtkAction *action,
 	}
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_WORK_OFFLINE:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action puts the application into offline mode.
+ *
+ * Main menu item: File -> Work Offline
+ **/
 static void
 action_work_offline_cb (GtkAction *action,
                         EShellWindow *shell_window)
@@ -1100,6 +1367,14 @@ action_work_offline_cb (GtkAction *action,
 	e_shell_set_line_status (shell, E_SHELL_LINE_STATUS_OFFLINE);
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_WORK_ONLINE:
+ * @window: an #EShellWindow
+ *
+ * Activation of this action puts the application into online mode.
+ *
+ * Main menu item: File -> Work Online
+ **/
 static void
 action_work_online_cb (GtkAction *action,
                        EShellWindow *shell_window)
@@ -1110,6 +1385,36 @@ action_work_online_cb (GtkAction *action,
 	e_shell_set_line_status (shell, E_SHELL_LINE_STATUS_ONLINE);
 }
 
+/**
+ * E_SHELL_WINDOW_ACTION_GROUP_CUSTOM_RULES:
+ * @window: an #EShellWindow
+ **/
+
+/**
+ * E_SHELL_WINDOW_ACTION_GROUP_GAL_VIEW:
+ * @window: an #EShellWindow
+ **/
+
+/**
+ * E_SHELL_WINDOW_ACTION_GROUP_NEW_ITEM:
+ * @window: an #EShellWindow
+ **/
+
+/**
+ * E_SHELL_WINDOW_ACTION_GROUP_NEW_SOURCE:
+ * @window: an #EShellWindow
+ **/
+
+/**
+ * E_SHELL_WINDOW_ACTION_GROUP_SHELL:
+ * @window: an #EShellWindow
+ **/
+
+/**
+ * E_SHELL_WINDOW_ACTION_GROUP_SWITCHER:
+ * @window: an #EShellWindow
+ **/
+
 static GtkActionEntry shell_entries[] = {
 
 	{ "about",
@@ -1360,7 +1665,7 @@ static GtkToggleActionEntry shell_toggle_entries[] = {
 
 	{ "show-toolbar",
 	  NULL,
-	  N_("Show _Toolbar"),
+	  N_("Show _Tool Bar"),
 	  NULL,
 	  N_("Show the toolbar"),
 	  G_CALLBACK (action_show_toolbar_cb),
diff --git a/shell/e-shell-window-actions.h b/shell/e-shell-window-actions.h
index 858c8541ce..b3858ad55c 100644
--- a/shell/e-shell-window-actions.h
+++ b/shell/e-shell-window-actions.h
@@ -32,6 +32,8 @@
 	E_SHELL_WINDOW_ACTION ((window), "about")
 #define E_SHELL_WINDOW_ACTION_CLOSE(window) \
 	E_SHELL_WINDOW_ACTION ((window), "close")
+#define E_SHELL_WINDOW_ACTION_CONTENTS(window) \
+	E_SHELL_WINDOW_ACTION ((window), "contents")
 #define E_SHELL_WINDOW_ACTION_FAQ(window) \
 	E_SHELL_WINDOW_ACTION ((window), "faq")
 #define E_SHELL_WINDOW_ACTION_FORGET_PASSWORDS(window) \
@@ -42,8 +44,6 @@
 	E_SHELL_WINDOW_ACTION ((window), "gal-define-views")
 #define E_SHELL_WINDOW_ACTION_GAL_SAVE_CUSTOM_VIEW(window) \
 	E_SHELL_WINDOW_ACTION ((window), "gal-save-custom-view")
-#define E_SHELL_WINDOW_ACTION_GAL_VIEW_MENU(window) \
-	E_SHELL_WINDOW_ACTION ((window), "gal-view-menu")
 #define E_SHELL_WINDOW_ACTION_IMPORT(window) \
 	E_SHELL_WINDOW_ACTION ((window), "import")
 #define E_SHELL_WINDOW_ACTION_NEW_WINDOW(window) \
@@ -80,8 +80,14 @@
 	E_SHELL_WINDOW_ACTION ((window), "show-toolbar")
 #define E_SHELL_WINDOW_ACTION_SUBMIT_BUG(window) \
 	E_SHELL_WINDOW_ACTION ((window), "submit-bug")
+#define E_SHELL_WINDOW_ACTION_SWITCHER_STYLE_BOTH(window) \
+	E_SHELL_WINDOW_ACTION ((window), "switcher-style-both")
 #define E_SHELL_WINDOW_ACTION_SWITCHER_STYLE_ICONS(window) \
 	E_SHELL_WINDOW_ACTION ((window), "switcher-style-icons")
+#define E_SHELL_WINDOW_ACTION_SWITCHER_STYLE_TEXT(window) \
+	E_SHELL_WINDOW_ACTION ((window), "switcher-style-text")
+#define E_SHELL_WINDOW_ACTION_SWITCHER_STYLE_USER(window) \
+	E_SHELL_WINDOW_ACTION ((window), "switcher-style-user")
 #define E_SHELL_WINDOW_ACTION_SYNC_OPTIONS(window) \
 	E_SHELL_WINDOW_ACTION ((window), "sync-options")
 #define E_SHELL_WINDOW_ACTION_WORK_OFFLINE(window) \
@@ -100,7 +106,7 @@
 	E_SHELL_WINDOW_ACTION_GROUP ((window), "new-source")
 #define E_SHELL_WINDOW_ACTION_GROUP_SHELL(window) \
 	E_SHELL_WINDOW_ACTION_GROUP ((window), "shell")
-#define E_SHELL_WINDOW_ACTION_GROUP_SHELL_VIEW(window) \
-	E_SHELL_WINDOW_ACTION_GROUP ((window), "shell-view")
+#define E_SHELL_WINDOW_ACTION_GROUP_SWITCHER(window) \
+	E_SHELL_WINDOW_ACTION_GROUP ((window), "switcher")
 
 #endif /* E_SHELL_WINDOW_ACTIONS_H */
diff --git a/shell/e-shell-window-private.c b/shell/e-shell-window-private.c
index 6836e07fa8..aa24a6ca7a 100644
--- a/shell/e-shell-window-private.c
+++ b/shell/e-shell-window-private.c
@@ -407,7 +407,6 @@ e_shell_window_switch_to_view (EShellWindow *shell_window,
 {
 	GtkNotebook *notebook;
 	EShellView *shell_view;
-	GList *list;
 	gint page_num;
 
 	shell_view = e_shell_window_get_shell_view (shell_window, view_name);
diff --git a/shell/e-shell-window.h b/shell/e-shell-window.h
index 8ad69a7e65..ac584475a3 100644
--- a/shell/e-shell-window.h
+++ b/shell/e-shell-window.h
@@ -21,6 +21,12 @@
  *
  */
 
+/**
+ * SECTION: e-shell-window
+ * @short_description: the main window
+ * @include: shell/e-shell-window.h
+ **/
+
 #ifndef E_SHELL_WINDOW_H
 #define E_SHELL_WINDOW_H
 
@@ -51,6 +57,12 @@ typedef struct _EShellWindow EShellWindow;
 typedef struct _EShellWindowClass EShellWindowClass;
 typedef struct _EShellWindowPrivate EShellWindowPrivate;
 
+/**
+ * EShellWindow:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ **/
 struct _EShellWindow {
 	GtkWindow parent;
 	EShellWindowPrivate *priv;
diff --git a/shell/e-shell.h b/shell/e-shell.h
index 5b804b3f4a..544872a554 100644
--- a/shell/e-shell.h
+++ b/shell/e-shell.h
@@ -20,6 +20,12 @@
  *
  */
 
+/**
+ * SECTION: e-shell
+ * @short_description: the backbone of Evolution
+ * @include: shell/e-shell.h
+ **/
+
 #ifndef E_SHELL_H
 #define E_SHELL_H
 
@@ -53,6 +59,12 @@ typedef struct _EShellPrivate EShellPrivate;
 
 typedef enum _EShellLineStatus EShellLineStatus;
 
+/**
+ * EShell:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ **/
 struct _EShell {
 	GObject parent;
 	EShellPrivate *priv;