Doc fixes

https://bugzilla.gnome.org/show_bug.cgi?id=663277

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

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

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)

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

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)

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)

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

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.
  */

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

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());

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

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

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

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)

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,

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,

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

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,

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