libeshell documentation cleanups.

11 files changed, 52 insertions, 63 deletions

diff --git a/doc/reference/libeshell/Makefile.am b/doc/reference/libeshell/Makefile.am
index 7262075b74..c9afa908ae 100644
--- a/doc/reference/libeshell/Makefile.am
+++ b/doc/reference/libeshell/Makefile.am
@@ -1,32 +1,11 @@
-# The name of the module, e.g. 'glib'.
+# The name of the module.
 DOC_MODULE=libeshell
 
-# The top-level SGML file. You can change this if you want to.
+# The top-level SGML file.
 DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
 
 # The directory containing the source code. Relative to $(srcdir).
-# 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=../../../shell
-
-# Extra options to pass to gtkdoc-scangobj. Not normally needed.
-SCANGOBJ_OPTIONS=
-
-# Extra options to supply to gtkdoc-scan.
-# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
-SCAN_OPTIONS=
-
-# Extra options to supply to gtkdoc-mkdb.
-MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space=e
-
-# Extra options to supply to gtkdoc-mktmpl
-# e.g. MKTMPL_OPTIONS=--only-section-tmpl
-MKTMPL_OPTIONS=
-
-# Extra options to supply to gtkdoc-fixref. Not normally needed.
-# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
-FIXXREF_OPTIONS=
+DOC_SOURCE_DIR=$(top_srcdir)/shell
 
 # Used for dependencies. The docs will be rebuilt if any of these change.
 HFILE_GLOB=$(top_srcdir)/shell/*.h
@@ -36,45 +15,29 @@ CFILE_GLOB=$(top_srcdir)/shell/*.c
 IGNORE_HFILES= \
 	evo-version.h \
 	e-shell-window-private.h \
-	es-event.h
-
-# Images to copy into HTML directory.
-HTML_IMAGES=
-
-# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
-content_files=
+	es-event.h \
+	$(NULL)
 
-# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
-# These files must be listed here *and* in content_files
-expand_content_files=
-
-# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
-# Only needed if you are using gtkdoc-scangobj to dynamically query widget
-# signals and properties.
 GTKDOC_CFLAGS= \
-	-I$(top_builddir)						\
 	-I$(top_srcdir)							\
+	-I$(top_builddir)						\
 	$(EVOLUTION_DATA_SERVER_CFLAGS)					\
-	$(GTKHTML_CFLAGS)
+	$(GNOME_PLATFORM_CFLAGS)					\
+	$(GTKHTML_CFLAGS)						\
+	$(NULL)
+
 GTKDOC_LIBS=								\
 	$(top_builddir)/libemail-engine/libemail-engine.la		\
 	$(top_builddir)/shell/libeshell.la				\
 	$(top_builddir)/e-util/libeutil.la				\
 	$(EVOLUTION_DATA_SERVER_LIBS)					\
-	$(GTKHTML_LIBS)
+	$(GNOME_PLATFORM_LIBS)						\
+	$(GTKHTML_LIBS)							\
+	$(NULL)
 
 # This includes the standard gtk-doc make rules, copied by gtkdocize.
 include $(top_srcdir)/gtk-doc.make
 
-# Other files to distribute
-# e.g. EXTRA_DIST += version.xml.in
-EXTRA_DIST +=
-
-# Files not to distribute
-# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
-# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
-#DISTCLEANFILES +=
-
 #TESTS = $(GTKDOC_CHECK)
 
 -include $(top_srcdir)/git.mk
diff --git a/doc/reference/libeshell/libeshell-docs.sgml b/doc/reference/libeshell/libeshell-docs.sgml
index 8a9404fdc9..22bc93fa19 100644
--- a/doc/reference/libeshell/libeshell-docs.sgml
+++ b/doc/reference/libeshell/libeshell-docs.sgml
@@ -3,7 +3,7 @@
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
   <bookinfo>
-    <title>Evolution Shell (libeshell)</title>
+    <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://library.gnome.org/devel/libeshell/">http://library.gnome.org/devel/libeshell/</ulink>.
diff --git a/doc/reference/libeshell/libeshell.types b/doc/reference/libeshell/libeshell.types
index b0038d55e1..2bc9a71963 100644
--- a/doc/reference/libeshell/libeshell.types
+++ b/doc/reference/libeshell/libeshell.types
@@ -1,3 +1,13 @@
+#include <shell/e-shell.h>
+#include <shell/e-shell-backend.h>
+#include <shell/e-shell-content.h>
+#include <shell/e-shell-searchbar.h>
+#include <shell/e-shell-sidebar.h>
+#include <shell/e-shell-switcher.h>
+#include <shell/e-shell-taskbar.h>
+#include <shell/e-shell-view.h>
+#include <shell/e-shell-window.h>
+
 e_shell_get_type
 e_shell_backend_get_type
 e_shell_content_get_type
diff --git a/shell/e-shell-backend.c b/shell/e-shell-backend.c
index d546bc7c1b..f4aed9b28b 100644
--- a/shell/e-shell-backend.c
+++ b/shell/e-shell-backend.c
@@ -609,8 +609,9 @@ e_shell_backend_start (EShellBackend *shell_backend)
  * e_shell_backend_is_started:
  * @shell_backend: an #EShellBackend
  *
- * Returns whether was shelll_backend already started, by
- * calling e_shell_backend_start().
+ * Returns whether e_shell_backend_start() was called for @shell_backend.
+ *
+ * Returns: whether @shell_backend is started
  **/
 gboolean
 e_shell_backend_is_started (EShellBackend *shell_backend)
diff --git a/shell/e-shell-migrate.c b/shell/e-shell-migrate.c
index 22552daeba..b36cfc06fe 100644
--- a/shell/e-shell-migrate.c
+++ b/shell/e-shell-migrate.c
@@ -882,13 +882,13 @@ e_shell_migrate_attempt (EShell *shell)
 		shell, "event::ready-to-start",
 		G_CALLBACK (shell_migrate_ready_to_start_event_cb), NULL);
 
-	/** @Event: Shell attempted upgrade
+	/* @Event: Shell attempted upgrade
 	 * @Id: upgrade.done
 	 * @Target: ESMenuTargetState
 	 *
 	 * This event is emitted whenever the shell successfully attempts
 	 * an upgrade.
-	 **/
+	 */
 	ese = es_event_peek ();
 	e_event_emit (
 		(EEvent *) ese, "upgrade.done",
diff --git a/shell/e-shell-switcher.h b/shell/e-shell-switcher.h
index b18546d58f..70b321309e 100644
--- a/shell/e-shell-switcher.h
+++ b/shell/e-shell-switcher.h
@@ -22,7 +22,7 @@
 #ifndef E_SHELL_SWITCHER_H
 #define E_SHELL_SWITCHER_H
 
-#include <e-shell-common.h>
+#include <shell/e-shell-common.h>
 
 /* Standard GObject macros */
 #define E_TYPE_SHELL_SWITCHER \
diff --git a/shell/e-shell-utils.c b/shell/e-shell-utils.c
index e790d5811a..1bdc82913d 100644
--- a/shell/e-shell-utils.c
+++ b/shell/e-shell-utils.c
@@ -285,11 +285,12 @@ e_shell_utils_import_uris (EShell *shell,
  * e_shell_hide_widgets_for_express_mode:
  * @shell: an #EShell
  * @builder: a #GtkBuilder
- * @widget_name: NULL-terminated list of strings
+ * @widget_name: first widget name to hide
+ * @...: %NULL-terminated list of additional widget names to hide
  *
  * If Evolution is running in Express mode (i.e. if the specified @shell is
  * in Express mode), then this function will hide a list of widgets, based
- * on their specified names.  The list of names must be NULL-terminated,
+ * on their specified names.  The list of names must be %NULL-terminated,
  * and each element of that list must be the name of a widget present in
  * @builder.  Those widgets will then get hidden.
  *
diff --git a/shell/e-shell-view.c b/shell/e-shell-view.c
index e6626666b3..9b3aa4a0f1 100644
--- a/shell/e-shell-view.c
+++ b/shell/e-shell-view.c
@@ -1401,6 +1401,8 @@ e_shell_view_get_search_rule (EShellView *shell_view)
  * @shell_view: an #EShellView
  *
  * Returns the searchbar widget for @shell_view.
+ *
+ * Returns: the searchbar widget for @shell_view
  **/
 GtkWidget *
 e_shell_view_get_searchbar (EShellView *shell_view)
@@ -1688,7 +1690,10 @@ e_shell_view_unblock_execute_search (EShellView *shell_view)
  * e_shell_view_is_execute_search_blocked:
  * @shell_view: an #EShellView
  *
- * Returns whether e_shell_view_execute_search() is blocked.
+ * Returns whether e_shell_view_execute_search() is blocked as a result
+ * of previous e_shell_view_block_execute_search() calls.
+ *
+ * Returns: %TRUE if e_shell_view_execute_search() is blocked
  **/
 gboolean
 e_shell_view_is_execute_search_blocked (EShellView *shell_view)
diff --git a/shell/e-shell-view.h b/shell/e-shell-view.h
index 6aea66f536..65c32b2982 100644
--- a/shell/e-shell-view.h
+++ b/shell/e-shell-view.h
@@ -108,6 +108,16 @@ struct _EShellView {
  *			See e_shell_view_get_shell_sidebar().
  * @new_shell_taskbar:	Factory method for the shell view's #EShellTaskbar.
  *			See e_shell_view_get_shell_taskbar().
+ * @new_shell_searchbar:
+ *			Factory method for the shell view's #EShellSearchbar.
+ *			See e_shell_view_get_searchbar().
+ * @construct_searchbar:
+ *			Class method to create, configure and pack a search
+ *			bar widget.  The search bar differs in normal shell
+ *			mode versus "express" mode.
+ * @get_search_name:	Class method to obtain a suitable name for the
+ *			current search criteria.  Subclasses should rarely
+ *			need to override the default behavior.
  * @toggled:		Class method for the #EShellView::toggled signal.
  *			Subclasses should rarely need to override the
  *			default behavior.
diff --git a/shell/e-shell.h b/shell/e-shell.h
index 84bb9f2d5c..a0ef1f6bae 100644
--- a/shell/e-shell.h
+++ b/shell/e-shell.h
@@ -57,7 +57,6 @@ typedef struct _EShellPrivate EShellPrivate;
 
 /**
  * EShellQuitReason:
- *
  * @E_SHELL_QUIT_ACTION:
  *   @E_SHELL_WINDOW_ACTION_QUIT was activated.
  * @E_SHELL_QUIT_LAST_WINDOW:
diff --git a/shell/es-event.c b/shell/es-event.c
index 4dc3a5ad25..2fdf432ba0 100644
--- a/shell/es-event.c
+++ b/shell/es-event.c
@@ -56,7 +56,7 @@ es_event_peek (void)
 {
 	if (es_event == NULL) {
 		es_event = g_object_new (es_event_get_type (), NULL);
-		/** @HookPoint: Shell Events Hookpoint
+		/* @HookPoint: Shell Events Hookpoint
 		 * Id: org.gnome.evolution.shell.events
 		 *
 		 * This is the hook point which emits shell events.
@@ -100,12 +100,12 @@ es_event_hook_class_init (ESEventHookClass *class)
 	EEventHookClass *event_hook_class;
 	gint i;
 
-	/** @HookClass: Shell Main Menu
+	/* @HookClass: Shell Main Menu
 	 * @Id: org.gnome.evolution.shell.events:1.0
 	 * @Target: ESEventTargetState
 	 *
 	 * A hook for events coming from the shell.
-	 **/
+	 */
 
 	plugin_hook_class = E_PLUGIN_HOOK_CLASS (class);
 	plugin_hook_class->id = "org.gnome.evolution.shell.events:1.0";