Fix documentation warnings

gobject-introspection now emits many more warnings for malformed
comments, and they fail the build.

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

src/gvc/gvc-channel-map.c

@@ -122,7 +122,6 @@ gvc_channel_map_get_mapping (const GvcChannelMap  *map)
 
 /**
  * gvc_channel_map_has_position: (skip)
- *
  * @map:
  * @position:
  *

src/gvc/gvc-mixer-card.c

@@ -146,7 +146,6 @@ gvc_mixer_card_set_icon_name (GvcMixerCard *card,
 
 /**
  * gvc_mixer_card_get_profile: (skip)
- *
  * @card:
  *
  * Returns:

src/gvc/gvc-mixer-control.c

@@ -113,7 +113,6 @@ gvc_mixer_control_get_pa_context (GvcMixerControl *control)
 
 /**
  * gvc_mixer_control_get_event_sink_input:
- *
  * @control:
  *
  * Returns: (transfer none):
@@ -231,7 +230,6 @@ gvc_mixer_control_set_default_source (GvcMixerControl *control,
 
 /**
  * gvc_mixer_control_get_default_sink:
- *
  * @control:
  *
  * Returns: (transfer none):
@@ -255,7 +253,6 @@ gvc_mixer_control_get_default_sink (GvcMixerControl *control)
 
 /**
  * gvc_mixer_control_get_default_source:
- *
  * @control:
  *
  * Returns: (transfer none):
@@ -287,7 +284,6 @@ gvc_mixer_control_lookup_id (GHashTable *hash_table,
 
 /**
  * gvc_mixer_control_lookup_stream_id:
- *
  * @control:
  * @id:
  *
@@ -304,7 +300,6 @@ gvc_mixer_control_lookup_stream_id (GvcMixerControl *control,
 
 /**
  * gvc_mixer_control_lookup_card_id:
- *
  * @control:
  * @id:
  *
@@ -361,7 +356,6 @@ gvc_card_collate (GvcMixerCard *a,
 
 /**
  * gvc_mixer_control_get_cards:
- *
  * @control:
  *
  * Returns: (transfer container) (element-type Gvc.MixerCard):
@@ -398,7 +392,6 @@ gvc_stream_collate (GvcMixerStream *a,
 
 /**
  * gvc_mixer_control_get_streams:
- *
  * @control:
  *
  * Returns: (transfer container) (element-type Gvc.MixerStream):
@@ -419,7 +412,6 @@ gvc_mixer_control_get_streams (GvcMixerControl *control)
 
 /**
  * gvc_mixer_control_get_sinks:
- *
  * @control:
  *
  * Returns: (transfer container) (element-type Gvc.MixerSink):
@@ -440,7 +432,6 @@ gvc_mixer_control_get_sinks (GvcMixerControl *control)
 
 /**
  * gvc_mixer_control_get_sources:
- *
  * @control:
  *
  * Returns: (transfer container) (element-type Gvc.MixerSource):
@@ -461,7 +452,6 @@ gvc_mixer_control_get_sources (GvcMixerControl *control)
 
 /**
  * gvc_mixer_control_get_sink_inputs:
- *
  * @control:
  *
  * Returns: (transfer container) (element-type Gvc.MixerSinkInput):
@@ -482,7 +472,6 @@ gvc_mixer_control_get_sink_inputs (GvcMixerControl *control)
 
 /**
  * gvc_mixer_control_get_source_outputs:
- *
  * @control:
  *
  * Returns: (transfer container) (element-type Gvc.MixerSourceOutput):

src/gvc/gvc-mixer-event-role.c

@@ -206,9 +206,8 @@ gvc_mixer_event_role_finalize (GObject *object)
 
 /**
  * gvc_mixer_event_role_new: (skip)
- *
  * @context:
- * @index:
+ * @device:
  * @channel_map:
  *
  * Returns:

src/gvc/gvc-mixer-sink-input.c

@@ -142,10 +142,9 @@ gvc_mixer_sink_input_finalize (GObject *object)
 
 /**
  * gvc_mixer_sink_input_new: (skip)
- *
  * @context:
  * @index:
- * @channel_map:
+ * @map:
  *
  * Returns:
  */

src/gvc/gvc-mixer-sink.c

@@ -175,10 +175,9 @@ gvc_mixer_sink_finalize (GObject *object)
 
 /**
  * gvc_mixer_sink_new: (skip)
- *
  * @context:
  * @index:
- * @channel_map:
+ * @map:
  *
  * Returns:
  */

src/gvc/gvc-mixer-source-output.c

@@ -97,10 +97,9 @@ gvc_mixer_source_output_finalize (GObject *object)
 
 /**
  * gvc_mixer_source_output_new: (skip)
- *
  * @context:
  * @index:
- * @channel_map:
+ * @map:
  *
  * Returns:
  */

src/gvc/gvc-mixer-source.c

@@ -175,10 +175,9 @@ gvc_mixer_source_finalize (GObject *object)
 
 /**
  * gvc_mixer_source_new: (skip)
- *
  * @context:
  * @index:
- * @channel_map:
+ * @map:
  *
  * Returns:
  */

src/gvc/gvc-mixer-stream.c

@@ -130,7 +130,6 @@ gvc_mixer_stream_get_channel_map (GvcMixerStream *stream)
 
 /**
  * gvc_mixer_stream_get_volume:
- *
  * @stream:
  *
  * Returns: (type guint32) (transfer none):
@@ -154,7 +153,6 @@ gvc_mixer_stream_get_decibel (GvcMixerStream *stream)
 
 /**
  * gvc_mixer_stream_set_volume:
- *
  * @stream:
  * @volume: (type guint32):
  *
@@ -420,7 +418,6 @@ gvc_mixer_stream_set_icon_name (GvcMixerStream *stream,
 
 /**
  * gvc_mixer_stream_get_base_volume:
- *
  * @stream:
  *
  * Returns: (type guint32) (transfer none):
@@ -435,7 +432,6 @@ gvc_mixer_stream_get_base_volume (GvcMixerStream *stream)
 
 /**
  * gvc_mixer_stream_set_base_volume:
- *
  * @stream:
  * @base_volume: (type guint32):
  *

src/shell-app-system.c

@@ -470,7 +470,7 @@ shell_app_system_get_settings_tree (ShellAppSystem *self)
 
 /**
  * shell_app_system_lookup_setting:
- * @self:
+ * @system:
  * @id: desktop file id
  *
  * Returns: (transfer none): Application in gnomecc.menu, or %NULL if none
@@ -610,7 +610,7 @@ shell_app_system_lookup_heuristic_basename (ShellAppSystem *system,
 
 /**
  * shell_app_system_get_all:
- * @self:
+ * @system:
  *
  * Returns: (transfer container) (element-type ShellApp): All installed applications
  */

src/shell-contact-system.c

@@ -90,7 +90,7 @@ shell_contact_system_class_init (ShellContactSystemClass *klass)
   g_type_class_add_private (object_class, sizeof (ShellContactSystemPrivate));
 }
 
-/**
+/*
  * normalize_terms:
  * @terms: (element-type utf8): Input search terms
  *

src/shell-global.c

@@ -1102,7 +1102,7 @@ shell_global_end_modal (ShellGlobal *global,
 }
 
 /**
- * shell_global_create_pointer_barrier
+ * shell_global_create_pointer_barrier:
  * @global: a #ShellGlobal
  * @x1: left X coordinate
  * @y1: top Y coordinate
@@ -1133,7 +1133,7 @@ shell_global_create_pointer_barrier (ShellGlobal *global,
 }
 
 /**
- * shell_global_destroy_pointer_barrier
+ * shell_global_destroy_pointer_barrier:
  * @global: a #ShellGlobal
  * @barrier: a pointer barrier
  *

src/shell-keyring-prompt.c

@@ -322,7 +322,7 @@ shell_keyring_prompt_class_init (ShellKeyringPromptClass *klass)
   g_object_class_override_property (gobject_class, PROP_CANCEL_LABEL, "cancel-label");
 
   /**
-   * ShellKeyringPrompt:password-visible
+   * ShellKeyringPrompt:password-visible:
    *
    * Whether the password entry is visible or not.
    */
@@ -331,7 +331,7 @@ shell_keyring_prompt_class_init (ShellKeyringPromptClass *klass)
                                    FALSE, G_PARAM_READABLE));
 
   /**
-    * ShellKeyringPrompt:confirm-visible
+    * ShellKeyringPrompt:confirm-visible:
     *
     * Whether the password confirm entry is visible or not.
     */
@@ -340,7 +340,7 @@ shell_keyring_prompt_class_init (ShellKeyringPromptClass *klass)
                                    FALSE, G_PARAM_READABLE));
 
   /**
-   * ShellKeyringPrompt:warning-visible
+   * ShellKeyringPrompt:warning-visible:
    *
    * Whether the warning label is visible or not.
    */
@@ -349,7 +349,7 @@ shell_keyring_prompt_class_init (ShellKeyringPromptClass *klass)
                                    FALSE, G_PARAM_READABLE));
 
   /**
-   * ShellKeyringPrompt:choice-visible
+   * ShellKeyringPrompt:choice-visible:
    *
    * Whether the choice check box is visible or not.
    */
@@ -358,7 +358,7 @@ shell_keyring_prompt_class_init (ShellKeyringPromptClass *klass)
                                    FALSE, G_PARAM_READABLE));
 
   /**
-   * ShellKeyringPrompt:password-actor
+   * ShellKeyringPrompt:password-actor:
    *
    * Text field for password
    */
@@ -367,7 +367,7 @@ shell_keyring_prompt_class_init (ShellKeyringPromptClass *klass)
                                    CLUTTER_TYPE_TEXT, G_PARAM_READWRITE));
 
   /**
-   * ShellKeyringPrompt:confirm-actor
+   * ShellKeyringPrompt:confirm-actor:
    *
    * Text field for confirmation password
    */

src/shell-screenshot.c

@@ -322,7 +322,6 @@ shell_screenshot_screenshot_area (ShellScreenshot *screenshot,
  * @screenshot: the #ShellScreenshot
  * @include_frame: Whether to include the frame or not
  * @include_cursor: Whether to include the cursor or not
- *
  * @filename: The filename for the screenshot
  * @callback: (scope async): function to call returning success or failure
  * of the async grabbing

src/shell-window-tracker.c

@@ -742,7 +742,7 @@ on_focus_window_changed (MetaDisplay        *display,
 
 /**
  * shell_window_tracker_get_startup_sequences:
- * @self:
+ * @tracker:
  *
  * Returns: (transfer none) (element-type ShellStartupSequence): Currently active startup sequences
  */

src/shell-wm.c

@@ -141,7 +141,7 @@ shell_wm_completed_switch_workspace (ShellWM *wm)
 }
 
 /**
- * shell_wm_completed_minimize
+ * shell_wm_completed_minimize:
  * @wm: the ShellWM
  * @actor: the MetaWindowActor actor
  *
@@ -155,7 +155,7 @@ shell_wm_completed_minimize (ShellWM         *wm,
 }
 
 /**
- * shell_wm_completed_maximize
+ * shell_wm_completed_maximize:
  * @wm: the ShellWM
  * @actor: the MetaWindowActor actor
  *
@@ -169,7 +169,7 @@ shell_wm_completed_maximize (ShellWM         *wm,
 }
 
 /**
- * shell_wm_completed_unmaximize
+ * shell_wm_completed_unmaximize:
  * @wm: the ShellWM
  * @actor: the MetaWindowActor actor
  *
@@ -183,7 +183,7 @@ shell_wm_completed_unmaximize (ShellWM         *wm,
 }
 
 /**
- * shell_wm_completed_map
+ * shell_wm_completed_map:
  * @wm: the ShellWM
  * @actor: the MetaWindowActor actor
  *
@@ -197,7 +197,7 @@ shell_wm_completed_map (ShellWM         *wm,
 }
 
 /**
- * shell_wm_completed_destroy
+ * shell_wm_completed_destroy:
  * @wm: the ShellWM
  * @actor: the MetaWindowActor actor
  *

src/st/st-adjustment.h

@@ -57,7 +57,7 @@ struct _StAdjustment
 };
 
 /**
- * StAdjustmentClass
+ * StAdjustmentClass:
  * @changed: Class handler for the ::changed signal.
  *
  * Base class for #StAdjustment.

src/st/st-texture-cache.c

@@ -328,7 +328,6 @@ texture_load_data_destroy (gpointer p)
 
 /**
  * on_image_size_prepared:
- *
  * @pixbuf_loader: #GdkPixbufLoader loading the image
  * @width: the original width of the image
  * @height: the original height of the image
@@ -1241,7 +1240,6 @@ st_texture_cache_load_icon_name (StTextureCache    *cache,
 
 /**
  * st_texture_cache_load_uri_async:
- *
  * @cache: The texture cache instance
  * @uri: uri of the image file from which to create a pixbuf
  * @available_width: available width for the image, can be -1 if not limited

src/st/st-theme.c

@@ -518,7 +518,7 @@ class_add_sel_matches_style (CRAdditionalSel *a_add_sel,
   return string_in_list (a_add_sel->content.class_name->stryng, element_class);
 }
 
-/**
+/*
  *@return TRUE if the additional attribute selector matches
  *the current style node given in argument, FALSE otherwise.
  *@param a_add_sel the additional attribute selector to consider.
@@ -616,7 +616,7 @@ element_name_matches_type (const char *element_name,
     }
 }
 
-/**
+/*
  *Evaluate a selector (a simple selectors list) and says
  *if it matches the style node given in parameter.
  *The algorithm used here is the following:

src/st/st-types.h

@@ -14,6 +14,18 @@
  * You should have received a copy of the GNU Lesser General Public License
  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  */
+#ifndef __ST_TYPES_H__
+#define __ST_TYPES_H__
+
+#if !defined(ST_H_INSIDE) && !defined(ST_COMPILATION)
+#error "Only <st/st.h> can be included directly.h"
+#endif
+
+#include <glib-object.h>
+#include <clutter/clutter.h>
+#include <gtk/gtk.h>
+
+G_BEGIN_DECLS
 
 /**
  * SECTION:st-types
@@ -22,20 +34,6 @@
  * Common types for StWidgets.
  */
 
-
-#if !defined(ST_H_INSIDE) && !defined(ST_COMPILATION)
-#error "Only <st/st.h> can be included directly.h"
-#endif
-
-#ifndef __ST_TYPES_H__
-#define __ST_TYPES_H__
-
-#include <glib-object.h>
-#include <clutter/clutter.h>
-#include <gtk/gtk.h>
-
-G_BEGIN_DECLS
-
 typedef enum {
   ST_ALIGN_START,
   ST_ALIGN_MIDDLE,

src/st/st-widget.c

@@ -855,7 +855,7 @@ st_widget_class_init (StWidgetClass *klass)
                                                         ST_PARAM_READWRITE));
 
   /**
-   * StWidget:theme
+   * StWidget:theme:
    *
    * A theme set on this actor overriding the global theming for this actor
    * and its descendants
@@ -2145,7 +2145,6 @@ st_describe_actor (ClutterActor *actor)
 
 /**
  * st_set_slow_down_factor:
- *
  * @factor: new slow-down factor
  *
  * Set a global factor applied to all animation durations

src/st/st-widget.h

@@ -78,7 +78,7 @@ struct _StWidgetClass
   /* vfuncs */
 
   /**
-   * StWidgetClass::navigate_focus
+   * StWidgetClass::navigate_focus:
    * @self: the "top level" container
    * @from: (allow-none): the actor that the focus is coming from
    * @direction: the direction focus is moving in