Add GObject Introspection annotations

Add GObject Introspection annotations to methods where needed, in
particular adding (transfer none) to return values that don't transfer
ownership.

st_texture_cache_get_actor() and st_texture_cache_get_texture()
are annotated as (transfer none) since they return a newly
created *floating* texture.

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

src/st/st-bin.c

@@ -617,7 +617,7 @@ st_bin_set_child (StBin        *bin,
  *
  * Retrieves a pointer to the child of @bin.
  *
- * Return value: a #ClutterActor, or %NULL
+ * Return value: (transfer none): a #ClutterActor, or %NULL
  */
 ClutterActor *
 st_bin_get_child (StBin *bin)

src/st/st-clipboard.c

@@ -285,8 +285,8 @@ st_clipboard_x11_event_filter (XEvent          *xev,
  *
  * Get the global #StClipboard object that represents the clipboard.
  *
- * Returns: a #StClipboard owned by St and must not be unrefferenced or
+ * Returns: (transfer none): a #StClipboard owned by St and must not be
- * freed.
+ * unrefferenced or freed.
  */
 StClipboard*
 st_clipboard_get_default (void)

src/st/st-entry.c

@@ -810,8 +810,8 @@ st_entry_set_text (StEntry     *entry,
  *
  * Retrieve the internal #ClutterText so that extra parameters can be set
  *
- * Returns: the #ClutterText used by #StEntry. The entry is owned by the
+ * Returns: (transfer none): ethe #ClutterText used by #StEntry. The entry is
- * #StEntry and should not be unref'ed by the application.
+ * owned by the #StEntry and should not be unref'ed by the application.
  */
 ClutterActor*
 st_entry_get_clutter_text (StEntry *entry)

src/st/st-label.c

@@ -351,8 +351,8 @@ st_label_set_text (StLabel     *label,
  *
  * Retrieve the internal #ClutterText so that extra parameters can be set
  *
- * Returns: the #ClutterText used by #StLabel. The label is owned by the
+ * Returns: (transfer none): ethe #ClutterText used by #StLabel. The label
- * #StLabel and should not be unref'ed by the application.
+ * is owned by the #StLabel and should not be unref'ed by the application.
  */
 ClutterActor*
 st_label_get_clutter_text (StLabel *label)

src/st/st-scroll-bar.c

@@ -1095,6 +1095,15 @@ st_scroll_bar_set_adjustment (StScrollBar  *bar,
     }
 }
 
+/**
+ * st_scroll_bar_get_adjustment:
+ * @bar: a #StScrollbar
+ *
+ * Gets the adjustment object that stores the current position
+ * of the scrollbar.
+ *
+ * Return value: (transfer none): the adjustment
+ */
 StAdjustment *
 st_scroll_bar_get_adjustment (StScrollBar *bar)
 {

src/st/st-scroll-view.c

@@ -709,6 +709,14 @@ st_scroll_view_new (void)
   return g_object_new (ST_TYPE_SCROLL_VIEW, NULL);
 }
 
+/**
+ * st_scroll_view_get_hscroll_bar:
+ * @scroll: a #StScrollView
+ *
+ * Gets the horizontal scrollbar of the scrollbiew
+ *
+ * Return value: (transfer none): the horizontal #StScrollbar
+ */
 ClutterActor *
 st_scroll_view_get_hscroll_bar (StScrollView *scroll)
 {
@@ -717,6 +725,14 @@ st_scroll_view_get_hscroll_bar (StScrollView *scroll)
   return scroll->priv->hscroll;
 }
 
+/**
+ * st_scroll_view_get_vscroll_bar:
+ * @scroll: a #StScrollView
+ *
+ * Gets the vertical scrollbar of the scrollbiew
+ *
+ * Return value: (transfer none): the vertical #StScrollbar
+ */
 ClutterActor *
 st_scroll_view_get_vscroll_bar (StScrollView *scroll)
 {

src/st/st-scroll-view.h

@@ -70,7 +70,6 @@ StWidget *st_scroll_view_new (void);
 
 ClutterActor *st_scroll_view_get_hscroll_bar     (StScrollView *scroll);
 ClutterActor *st_scroll_view_get_vscroll_bar     (StScrollView *scroll);
-ClutterActor *st_scroll_view_get_child           (StScrollView *scroll);
 
 gfloat        st_scroll_view_get_column_size     (StScrollView *scroll);
 void          st_scroll_view_set_column_size     (StScrollView *scroll,

src/st/st-scrollable.c

@@ -77,6 +77,14 @@ st_scrollable_set_adjustments (StScrollable *scrollable,
                                                              vadjustment);
 }
 
+/**
+ * st_scroll_bar_get_adjustments:
+ * @hadjustment: (transfer none) (out) (allow-none): location to store the horizontal adjustment, or %NULL
+ * @vadjustment: (transfer none) (out) (allow-none): location to store the vertical adjustment, or %NULL
+ *
+ * Gets the adjustment objects that store the offsets of the scrollable widget
+ * into its possible scrolling area.
+ */
 void
 st_scrollable_get_adjustments (StScrollable  *scrollable,
                                StAdjustment **hadjustment,

src/st/st-stylable.c

@@ -337,12 +337,12 @@ st_stylable_iface_install_property (StStylableIface *iface,
 /**
  * st_stylable_list_properties:
  * @stylable: a #StStylable
- * @n_props: return location for the number of properties, or %NULL
+ * @n_props: (out): return location for the number of properties, or %NULL
  *
  * Retrieves all the #GParamSpec<!-- -->s installed by @stylable.
  *
- * Return value: an array of #GParamSpec<!-- -->s. Free it with
+ * Return value: (transfer container) (array length=n_props): an array
- *   g_free() when done.
+ *  of #GParamSpec<!-- -->s. Free it with  g_free() when done.
  */
 GParamSpec **
 st_stylable_list_properties (StStylable *stylable,
@@ -370,8 +370,8 @@ st_stylable_list_properties (StStylable *stylable,
  * Finds the #GParamSpec installed by @stylable for the property
  * with @property_name.
  *
- * Return value: a #GParamSpec for the given property, or %NULL if
+ * Return value: (transfer none): a #GParamSpec for the given property,
- *   no property with that name was found
+ *   or %NULL if no property with that name was found
  */
 GParamSpec *
 st_stylable_find_property (StStylable  *stylable,
@@ -413,7 +413,7 @@ st_stylable_get_property_internal (StStylable *stylable,
  * st_stylable_get_property:
  * @stylable: a #StStylable
  * @property_name: the name of the property
- * @value: return location for an empty #GValue
+ * @value: (out): return location for an empty #GValue
  *
  * Retrieves the value of @property_name for @stylable, and puts it
  * into @value.
@@ -514,7 +514,7 @@ st_stylable_get (StStylable  *stylable,
  * st_stylable_get_default_value:
  * @stylable: a #StStylable
  * @property_name: name of the property to query
- * @value_out: return location for the default value
+ * @value_out: (out): return location for the default value
  *
  * Query @stylable for the default value of property @property_name and
  * fill @value_out with the result.
@@ -559,7 +559,7 @@ st_stylable_get_default_value (StStylable  *stylable,
  * Retrieves the #StStyle used by @stylable. This function does not
  * alter the reference count of the returned object.
  *
- * Return value: a #StStyle
+ * Return value: (transfer none): a #StStyle
  */
 StStyle *
 st_stylable_get_style (StStylable *stylable)
@@ -624,7 +624,7 @@ st_stylable_set_style (StStylable *stylable,
  *
  * Obtain the parent #StStylable that contains @stylable.
  *
- * Return value: The parent #StStylable
+ * Return value: (transfer none): The parent #StStylable
  */
 StStylable*
 st_stylable_get_container (StStylable *stylable)
@@ -647,7 +647,7 @@ st_stylable_get_container (StStylable *stylable)
  *
  * Get the parent ancestor #StStylable of @stylable.
  *
- * Return value: the parent #StStylable
+ * Return value: (transfer none): the parent #StStylable
  */
 StStylable*
 st_stylable_get_base_style (StStylable *stylable)

src/st/st-style.c

@@ -356,8 +356,8 @@ st_style_new (void)
  * Return the default StStyle object. This includes the current theme (if
  * any).
  *
- * Returns: a #StStyle object. This must not be freed or unref'd by
+ * Returns: (transfer none): a #StStyle object. This must not be freed or
- * applications
+ * unref'd by applications
  */
 StStyle *
 st_style_get_default (void)
@@ -625,7 +625,7 @@ st_style_get_ccss_query (StStyle    *style,
  * @style: the style data store object
  * @stylable: a stylable to retreive the data for
  * @pspec: a #GParamSpec describing the property required
- * @value: a #GValue to place the return value in
+ * @value: (out): a #GValue to place the return value in
  *
  * Requests the property described in @pspec for the specified stylable
  */

src/st/st-subtexture.c

@@ -457,7 +457,7 @@ st_subtexture_new (ClutterTexture *texture,
  *
  * Return the texture used by the #StSubtexture
  *
- * Returns: a #ClutterTexture owned by the #StSubtexture
+ * Returns: (transfer none): a #ClutterTexture owned by the #StSubtexture
  */
 ClutterTexture *
 st_subtexture_get_parent_texture (StSubtexture *frame)

src/st/st-texture-cache.c

@@ -169,7 +169,7 @@ st_texture_cache_init (StTextureCache *self)
  * Returns the default texture cache. This is owned by St and should not be
  * unreferenced or freed.
  *
- * Returns: a StTextureCache
+ * Returns: (transfer none): a StTextureCache
  */
 StTextureCache*
 st_texture_cache_get_default (void)
@@ -243,7 +243,7 @@ add_texture_to_cache (StTextureCache     *self,
  * the same image path will return a new ClutterTexture with the previously
  * loaded image.
  *
- * Returns: a newly created ClutterTexture
+ * Returns: (transfer none): a newly created ClutterTexture
  */
 ClutterTexture*
 st_texture_cache_get_texture (StTextureCache *self,
@@ -317,7 +317,7 @@ st_texture_cache_get_texture (StTextureCache *self,
  *
  * Use this function if all you need is an actor for drawing.
  *
- * Returns: a newly created ClutterTexture
+ * Returns: (transfer none): a newly created ClutterTexture
  */
 ClutterActor*
 st_texture_cache_get_actor (StTextureCache *self,

src/st/st-texture-frame.c

@@ -501,7 +501,7 @@ st_texture_frame_new (ClutterTexture *texture,
  *
  * Return the texture used by the #StTextureFrame
  *
- * Returns: a #ClutterTexture owned by the #StTextureFrame
+ * Returns: (transfer none): a #ClutterTexture owned by the #StTextureFrame
  */
 ClutterTexture *
 st_texture_frame_get_parent_texture (StTextureFrame *frame)

src/st/st-widget.c

@@ -1122,7 +1122,7 @@ st_widget_ensure_style (StWidget *widget)
  * "border-image" CSS property. This function should normally only be used
  * by subclasses.
  *
- * Returns: #ClutterActor
+ * Returns: (transfer none): #ClutterActor
  */
 ClutterActor *
 st_widget_get_border_image (StWidget *actor)
@@ -1139,7 +1139,7 @@ st_widget_get_border_image (StWidget *actor)
  * "background-image" CSS property. This function should normally only be used
  * by subclasses.
  *
- * Returns: a #ClutterActor
+ * Returns: (transfer none): a #ClutterActor
  */
 ClutterActor *
 st_widget_get_background_image (StWidget *actor)