GNOME.org
 

[gnome-shell] Doc fixes

commit 628e59894b2cf990dd2cb1e84be37ed09c6de486
Author: Jasper St. Pierre <jstpierre mecheye net>
Date:   Wed Nov 2 12:24:49 2011 -0400

    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 b8c68d1..61cde1f 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 aceb298..f759d23 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 53d75ee..3d1e78a 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 78b1637..6572c56 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 0c7961a..b5f2edd 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 5d985ed..13a8b3e 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<Shell.MobileProvider>) (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 7132b87..72c4210 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 3c6bdef..59a517e 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 fe96c5b..5f00e6e 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 b0251d2..adb7fb7 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 6507d19..fd8f2e1 100644
--- a/src/shell-xfixes-cursor.c
+++ b/src/shell-xfixes-cursor.c
@@ -8,8 +8,8 @@
 #include <X11/extensions/Xfixes.h>
 
 /**
- * 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 1395af2..fac0124 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 92574ff..8c24440 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 63e66c1..6f6beb2 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 6e6ee3c..8805fb1 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 1c2856b..79ec931 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 46d38b6..795f875 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 2058e32..551fb2c 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 0a044bf..eb0103f 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
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]