From 628e59894b2cf990dd2cb1e84be37ed09c6de486 Mon Sep 17 00:00:00 2001 From: "Jasper St. Pierre" Date: Wed, 2 Nov 2011 12:24:49 -0400 Subject: [PATCH] Doc fixes https://bugzilla.gnome.org/show_bug.cgi?id=663277 --- docs/reference/shell/Makefile.am | 2 +- src/main.c | 2 +- src/shell-app.c | 7 ++++--- src/shell-doc-system.c | 9 +++++---- src/shell-global.c | 4 ++-- src/shell-mobile-providers.c | 6 +++--- src/shell-perf-log.c | 2 +- src/shell-recorder-src.c | 1 + src/shell-recorder.h | 4 ++-- src/shell-window-tracker.c | 4 ++-- src/shell-xfixes-cursor.c | 4 ++-- src/st/st-group.c | 2 +- src/st/st-im-text.c | 2 +- src/st/st-scroll-view.c | 4 ++-- src/st/st-theme-context.h | 2 +- src/st/st-theme-node.c | 8 ++++---- src/st/st-theme-node.h | 2 +- src/st/st-theme.c | 10 ++++++---- src/st/st-theme.h | 2 +- 19 files changed, 41 insertions(+), 36 deletions(-) diff --git a/docs/reference/shell/Makefile.am b/docs/reference/shell/Makefile.am index b8c68d174..61cde1f6f 100644 --- a/docs/reference/shell/Makefile.am +++ b/docs/reference/shell/Makefile.am @@ -58,7 +58,7 @@ EXTRA_HFILES= # Header files or dirs to ignore when scanning. Use base file/dir names # e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code -IGNORE_HFILES=calendar-server gvs hotplug-sniffer st tray +IGNORE_HFILES=calendar-server gvc hotplug-sniffer st tray # Images to copy into HTML directory. # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png diff --git a/src/main.c b/src/main.c index aceb298db..f759d23a8 100644 --- a/src/main.c +++ b/src/main.c @@ -96,7 +96,7 @@ shell_dbus_init (gboolean replace) guint32 request_name_flags; guint32 request_name_result; - /** TODO: + /* TODO: * In the future we should use GDBus for this. However, in * order to do that, we need to port all of the JavaScript * code. Otherwise, the name will be claimed on the wrong diff --git a/src/shell-app.c b/src/shell-app.c index 53d75ee15..3d1e78afa 100644 --- a/src/shell-app.c +++ b/src/shell-app.c @@ -1220,12 +1220,13 @@ shell_app_init_search_data (ShellApp *app) /** * shell_app_compare_by_name: - * @app: - * @other: + * @app: One app + * @other: The other app * * Order two applications by name. * - * Returns: -1, 0, or 1; suitable for use as a comparison function for e.g. g_slist_sort() + * Returns: -1, 0, or 1; suitable for use as a comparison function + * for e.g. g_slist_sort() */ int shell_app_compare_by_name (ShellApp *app, ShellApp *other) diff --git a/src/shell-doc-system.c b/src/shell-doc-system.c index 78b1637dd..6572c56a9 100644 --- a/src/shell-doc-system.c +++ b/src/shell-doc-system.c @@ -52,16 +52,17 @@ shell_doc_system_get_all (ShellDocSystem *self) } /** - * @self: A #ShellDocSystem - * @uri: Url + * shell_doc_system_lookup_by_uri: + * @system: A #ShellDocSystem + * @uri: URI * * Returns: (transfer none): Recent file info corresponding to given @uri */ GtkRecentInfo * -shell_doc_system_lookup_by_uri (ShellDocSystem *self, +shell_doc_system_lookup_by_uri (ShellDocSystem *system, const char *uri) { - return g_hash_table_lookup (self->priv->infos_by_uri, uri); + return g_hash_table_lookup (system->priv->infos_by_uri, uri); } static gboolean diff --git a/src/shell-global.c b/src/shell-global.c index 0c7961a43..b5f2eddec 100644 --- a/src/shell-global.c +++ b/src/shell-global.c @@ -857,7 +857,7 @@ _shell_global_get_gjs_context (ShellGlobal *global) * overview mode or the "looking glass" debug overlay, that block * application and normal key shortcuts. * - * Returns value: %TRUE if we succesfully entered the mode. %FALSE if we couldn't + * Returns: %TRUE if we succesfully entered the mode. %FALSE if we couldn't * enter the mode. Failure may occur because an application has the pointer * or keyboard grabbed, because Mutter is in a mode itself like moving a * window or alt-Tab window selection, or because shell_global_begin_modal() @@ -1964,7 +1964,7 @@ shell_global_screenshot_window (ShellGlobal *global, * will enable a login dialog and run in a more confined * way. This type is suitable for the display manager. * - * Returns the type of session gnome-shell is providing. + * Returns: the type of session gnome-shell is providing. */ ShellSessionType shell_global_get_session_type (ShellGlobal *global) diff --git a/src/shell-mobile-providers.c b/src/shell-mobile-providers.c index 5d985ed09..13a8b3ece 100644 --- a/src/shell-mobile-providers.c +++ b/src/shell-mobile-providers.c @@ -619,9 +619,9 @@ static const GMarkupParser mobile_parser = { * @out_ccs: (out) (allow-none): (element-type utf8 utf8): a #GHashTable containing * country codes * - * Returns: (element-type utf8 GList) (transfer container): a - * hash table where keys are country names 'char *', values are a 'GSList *' - * of 'ShellMobileProvider *'. Everything is destroyed with g_hash_table_destroy (). + * Returns: (element-type utf8 GList) (transfer container): a + * hash table where keys are country names #gchar, values are a #GSList + * of #ShellMobileProvider. Everything is destroyed with g_hash_table_destroy(). */ GHashTable * shell_mobile_providers_parse (GHashTable **out_ccs) diff --git a/src/shell-perf-log.c b/src/shell-perf-log.c index 7132b874c..72c4210e2 100644 --- a/src/shell-perf-log.c +++ b/src/shell-perf-log.c @@ -590,7 +590,7 @@ shell_perf_log_update_statistic_x (ShellPerfLog *perf_log, } /** - * shell_perf_log_add statistics_callback: + * shell_perf_log_add_statistics_callback: * @perf_log: a #ShellPerfLog * @callback: function to call before recording statistics * @user_data: data to pass to @callback diff --git a/src/shell-recorder-src.c b/src/shell-recorder-src.c index 3c6bdefcf..59a517e15 100644 --- a/src/shell-recorder-src.c +++ b/src/shell-recorder-src.c @@ -282,6 +282,7 @@ plugin_init (GstPlugin *plugin) /** * shell_recorder_src_register: + * * Registers a plugin holding our single element to use privately in * this application. Can safely be called multiple times. */ diff --git a/src/shell-recorder.h b/src/shell-recorder.h index fe96c5b5b..5f00e6ee1 100644 --- a/src/shell-recorder.h +++ b/src/shell-recorder.h @@ -7,8 +7,8 @@ G_BEGIN_DECLS /** - * SECTION:ShellRecorder - * short_description: Record from a #ClutterStage + * SECTION:shell-recorder + * @short_description: Record from a #ClutterStage * * The #ShellRecorder object is used to make recordings ("screencasts") * of a #ClutterStage. Recording is done via #GStreamer. The default is diff --git a/src/shell-window-tracker.c b/src/shell-window-tracker.c index b0251d270..adb7fb788 100644 --- a/src/shell-window-tracker.c +++ b/src/shell-window-tracker.c @@ -639,7 +639,7 @@ shell_window_tracker_get_window_app (ShellWindowTracker *tracker, /** * shell_window_tracker_get_app_from_pid: - * @self; A #ShellAppSystem + * @tracker: A #ShellAppSystem * @pid: A Unix process identifier * * Look up the application corresponding to a process. @@ -647,7 +647,7 @@ shell_window_tracker_get_window_app (ShellWindowTracker *tracker, * Returns: (transfer none): A #ShellApp, or %NULL if none */ ShellApp * -shell_window_tracker_get_app_from_pid (ShellWindowTracker *self, +shell_window_tracker_get_app_from_pid (ShellWindowTracker *tracker, int pid) { GSList *running = shell_app_system_get_running (shell_app_system_get_default()); diff --git a/src/shell-xfixes-cursor.c b/src/shell-xfixes-cursor.c index 6507d19a8..fd8f2e156 100644 --- a/src/shell-xfixes-cursor.c +++ b/src/shell-xfixes-cursor.c @@ -8,8 +8,8 @@ #include /** - * SECTION:ShellXFixesCursor - * short_description: Capture/manipulate system mouse cursor. + * SECTION:shell-xfixes-cursor + * @short_description: Capture/manipulate system mouse cursor. * * The #ShellXFixesCursor object uses the XFixes extension to show/hide the * the system mouse pointer, to grab its image as it changes, and emit a diff --git a/src/st/st-group.c b/src/st/st-group.c index 1395af211..fac012465 100644 --- a/src/st/st-group.c +++ b/src/st/st-group.c @@ -20,7 +20,7 @@ /** * SECTION:st-group - * SECTION:clutter-group + * @see_also:#ClutterGroup * @short_description: A fixed layout container * * A #StGroup is an Actor which contains multiple child actors positioned diff --git a/src/st/st-im-text.c b/src/st/st-im-text.c index 92574ff67..8c244403b 100644 --- a/src/st/st-im-text.c +++ b/src/st/st-im-text.c @@ -25,7 +25,7 @@ */ /** - * SECTION:StIMText + * SECTION:st-im-text * @short_description: Text widget with input method support * @stability: Unstable * @see_also: #ClutterText diff --git a/src/st/st-scroll-view.c b/src/st/st-scroll-view.c index 63e66c1a6..6f6beb219 100644 --- a/src/st/st-scroll-view.c +++ b/src/st/st-scroll-view.c @@ -963,7 +963,7 @@ st_scroll_view_new (void) * * Gets the horizontal scrollbar of the scrollbiew * - * Return value: (transfer none): the horizontal #StScrollbar + * Return value: (transfer none): the horizontal #StScrollBar */ ClutterActor * st_scroll_view_get_hscroll_bar (StScrollView *scroll) @@ -979,7 +979,7 @@ st_scroll_view_get_hscroll_bar (StScrollView *scroll) * * Gets the vertical scrollbar of the scrollbiew * - * Return value: (transfer none): the vertical #StScrollbar + * Return value: (transfer none): the vertical #StScrollBar */ ClutterActor * st_scroll_view_get_vscroll_bar (StScrollView *scroll) diff --git a/src/st/st-theme-context.h b/src/st/st-theme-context.h index 6e6ee3cb2..8805fb19b 100644 --- a/src/st/st-theme-context.h +++ b/src/st/st-theme-context.h @@ -29,7 +29,7 @@ G_BEGIN_DECLS /** - * SECTION:StThemeContext + * SECTION:st-theme-context * @short_description: holds global information about a tree of styled objects * * #StThemeContext is responsible for managing information global to a tree of styled objects, diff --git a/src/st/st-theme-node.c b/src/st/st-theme-node.c index 1c2856b8f..79ec93133 100644 --- a/src/st/st-theme-node.c +++ b/src/st/st-theme-node.c @@ -1476,7 +1476,7 @@ st_theme_node_get_outline_width (StThemeNode *node) * @node: a #StThemeNode * @color: (out caller-allocates): location to store the color * - * Returns the color of @node's outline. + * Gets the color of @node's outline. */ void st_theme_node_get_outline_color (StThemeNode *node, @@ -1745,7 +1745,7 @@ _st_theme_node_ensure_background (StThemeNode *node) * @node: a #StThemeNode * @color: (out caller-allocates): location to store the color * - * Returns @node's background color. + * Gets @node's background color. */ void st_theme_node_get_background_color (StThemeNode *node, @@ -1773,7 +1773,7 @@ st_theme_node_get_background_image (StThemeNode *node) * @node: a #StThemeNode * @color: (out caller-allocates): location to store the color * - * Returns @node's foreground color. + * Gets @node's foreground color. */ void st_theme_node_get_foreground_color (StThemeNode *node, @@ -1847,7 +1847,7 @@ st_theme_node_get_background_gradient (StThemeNode *node, * @side: a #StSide * @color: (out caller-allocates): location to store the color * - * Returns the color of @node's border on @side + * Gets the color of @node's border on @side */ void st_theme_node_get_border_color (StThemeNode *node, diff --git a/src/st/st-theme-node.h b/src/st/st-theme-node.h index 46d38b6aa..795f875c1 100644 --- a/src/st/st-theme-node.h +++ b/src/st/st-theme-node.h @@ -31,7 +31,7 @@ G_BEGIN_DECLS /** - * SECTION:StThemeNode + * SECTION:st-theme-node * @short_description: style information for one node in a tree of themed objects * * A #StThemeNode represents the CSS style information (the set of CSS properties) for one diff --git a/src/st/st-theme.c b/src/st/st-theme.c index 2058e32f1..551fb2c1f 100644 --- a/src/st/st-theme.c +++ b/src/st/st-theme.c @@ -491,10 +491,12 @@ pseudo_class_add_sel_matches_style (StTheme *a_this, } /** - *@param a_add_sel the class additional selector to consider. - *@param a_node the style node to consider. - *@return TRUE if the class additional selector matches - *the style node given in argument, FALSE otherwise. + * class_add_sel_matches_style: + * @a_add_sel: The class additional selector to consider. + * @a_node: The style node to consider. + * + * Returns: %TRUE if the class additional selector matches + * the style node given in argument, %FALSE otherwise. */ static gboolean class_add_sel_matches_style (CRAdditionalSel *a_add_sel, diff --git a/src/st/st-theme.h b/src/st/st-theme.h index 0a044bf3e..eb0103f92 100644 --- a/src/st/st-theme.h +++ b/src/st/st-theme.h @@ -27,7 +27,7 @@ G_BEGIN_DECLS /** - * SECTION:StTheme + * SECTION:st-theme * @short_description: a set of stylesheets * * #StTheme holds a set of stylesheets. (The "cascade" of the name