From 6b53dd8da13d35ce3e8130b25584371473927a4f Mon Sep 17 00:00:00 2001 From: Matthew Barnes Date: Thu, 13 Dec 2012 17:18:51 -0500 Subject: libeshell documentation cleanups. --- doc/reference/libeshell/Makefile.am | 63 ++++++----------------------- doc/reference/libeshell/libeshell-docs.sgml | 2 +- doc/reference/libeshell/libeshell.types | 10 +++++ shell/e-shell-backend.c | 5 ++- shell/e-shell-migrate.c | 4 +- shell/e-shell-switcher.h | 2 +- shell/e-shell-utils.c | 5 ++- shell/e-shell-view.c | 7 +++- shell/e-shell-view.h | 10 +++++ shell/e-shell.h | 1 - shell/es-event.c | 6 +-- 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"> - Evolution Shell (libeshell) + Evolution Shell Reference Manual The latest version of this documentation can be found on-line at http://library.gnome.org/devel/libeshell/. 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 +#include +#include +#include +#include +#include +#include +#include +#include + 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 +#include /* 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"; -- cgit v1.2.3