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.

clutter_texture_cache_get_actor() and clutter_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/nbtk/nbtk-bin.c

@@ -609,7 +609,7 @@ nbtk_bin_set_child (NbtkBin *bin,
  *
  * Retrieves a pointer to the child of @bin.
  *
- * Return value: a #ClutterActor, or %NULL
+ * Return value: (transfer none): a #ClutterActor, or %NULL
  */
 ClutterActor *
 nbtk_bin_get_child (NbtkBin *bin)

src/nbtk/nbtk-clipboard.c

@@ -272,11 +272,11 @@ nbtk_clipboard_x11_event_filter (XEvent          *xev,
  *
  * Get the global #NbtkClipboard object that represents the clipboard.
  *
- * Returns: a #NbtkClipboard owned by Nbtk and must not be unrefferenced or
+ * Returns: (transfer none): a #NbtkClipboard owned by Nbtk and must not be
- * freed.
+ * unrefferenced or freed.
  */
 NbtkClipboard*
-nbtk_clipboard_get_default ()
+nbtk_clipboard_get_default (void)
 {
   static NbtkClipboard *default_clipboard = NULL;
 

src/nbtk/nbtk-clipboard.h

@@ -85,7 +85,7 @@ typedef void (*NbtkClipboardCallbackFunc) (NbtkClipboard *clipboard,
 
 GType nbtk_clipboard_get_type (void);
 
-NbtkClipboard* nbtk_clipboard_get_default ();
+NbtkClipboard* nbtk_clipboard_get_default (void);
 void nbtk_clipboard_get_text (NbtkClipboard *clipboard, NbtkClipboardCallbackFunc callback, gpointer user_data);
 void nbtk_clipboard_set_text (NbtkClipboard *clipboard, const gchar *text);
 

src/nbtk/nbtk-entry.c

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

src/nbtk/nbtk-label.c

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

src/nbtk/nbtk-scroll-bar.c

@@ -1085,6 +1085,15 @@ nbtk_scroll_bar_set_adjustment (NbtkScrollBar *bar,
     }
 }
 
+/**
+ * nbtk_scroll_bar_get_adjustment:
+ * @bar: a #NbtkScrollbar
+ *
+ * Gets the adjustment object that stores the current position
+ * of the scrollbar.
+ *
+ * Return value: (transfer none): the adjustment
+ */
 NbtkAdjustment *
 nbtk_scroll_bar_get_adjustment (NbtkScrollBar *bar)
 {

src/nbtk/nbtk-scroll-view.c

@@ -695,6 +695,14 @@ nbtk_scroll_view_new (void)
   return g_object_new (NBTK_TYPE_SCROLL_VIEW, NULL);
 }
 
+/**
+ * nbtk_scroll_view_get_hscroll_bar:
+ * @scroll: a #NbtkScrollView
+ *
+ * Gets the horizontal scrollbar of the scrollbiew
+ *
+ * Return value: (transfer none): the horizontal #NbtkScrollbar
+ */
 ClutterActor *
 nbtk_scroll_view_get_hscroll_bar (NbtkScrollView *scroll)
 {
@@ -703,6 +711,14 @@ nbtk_scroll_view_get_hscroll_bar (NbtkScrollView *scroll)
   return scroll->priv->hscroll;
 }
 
+/**
+ * nbtk_scroll_view_get_vscroll_bar:
+ * @scroll: a #NbtkScrollView
+ *
+ * Gets the vertical scrollbar of the scrollbiew
+ *
+ * Return value: (transfer none): the vertical #NbtkScrollbar
+ */
 ClutterActor *
 nbtk_scroll_view_get_vscroll_bar (NbtkScrollView *scroll)
 {

src/nbtk/nbtk-scroll-view.h

@@ -70,7 +70,6 @@ NbtkWidget *  nbtk_scroll_view_new             (void);
 
 ClutterActor *  nbtk_scroll_view_get_hscroll_bar (NbtkScrollView *scroll);
 ClutterActor *  nbtk_scroll_view_get_vscroll_bar (NbtkScrollView *scroll);
-ClutterActor *  nbtk_scroll_view_get_child       (NbtkScrollView *scroll);
 
 gfloat     nbtk_scroll_view_get_column_size (NbtkScrollView *scroll);
 void            nbtk_scroll_view_set_column_size (NbtkScrollView *scroll,

src/nbtk/nbtk-scrollable.c

@@ -77,6 +77,14 @@ nbtk_scrollable_set_adjustments (NbtkScrollable *scrollable,
                                                                vadjustment);
 }
 
+/**
+ * nbtk_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
 nbtk_scrollable_get_adjustments (NbtkScrollable *scrollable,
                                  NbtkAdjustment **hadjustment,

src/nbtk/nbtk-stylable.c

@@ -337,12 +337,12 @@ nbtk_stylable_iface_install_property (NbtkStylableIface *iface,
 /**
  * nbtk_stylable_list_properties:
  * @stylable: a #NbtkStylable
- * @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 **
 nbtk_stylable_list_properties (NbtkStylable *stylable,
@@ -370,8 +370,8 @@ nbtk_stylable_list_properties (NbtkStylable *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 *
 nbtk_stylable_find_property (NbtkStylable *stylable,
@@ -413,7 +413,7 @@ nbtk_stylable_get_property_internal (NbtkStylable *stylable,
  * nbtk_stylable_get_property:
  * @stylable: a #NbtkStylable
  * @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 @@ nbtk_stylable_get (NbtkStylable *stylable,
  * nbtk_stylable_get_default_value:
  * @stylable: a #NbtkStylable
  * @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 @@ nbtk_stylable_get_default_value (NbtkStylable  *stylable,
  * Retrieves the #NbtkStyle used by @stylable. This function does not
  * alter the reference count of the returned object.
  *
- * Return value: a #NbtkStyle
+ * Return value: (transfer none): a #NbtkStyle
  */
 NbtkStyle *
 nbtk_stylable_get_style (NbtkStylable *stylable)
@@ -624,7 +624,7 @@ nbtk_stylable_set_style (NbtkStylable *stylable,
  *
  * Obtain the parent #NbtkStylable that contains @stylable.
  *
- * Return value: The parent #NbtkStylable
+ * Return value: (transfer none): The parent #NbtkStylable
  */
 NbtkStylable*
 nbtk_stylable_get_container (NbtkStylable *stylable)
@@ -647,7 +647,7 @@ nbtk_stylable_get_container (NbtkStylable *stylable)
  *
  * Get the parent ancestor #NbtkStylable of @stylable.
  *
- * Return value: the parent #NbtkStylable
+ * Return value: (transfer none): the parent #NbtkStylable
  */
 NbtkStylable*
 nbtk_stylable_get_base_style (NbtkStylable *stylable)

src/nbtk/nbtk-style.c

@@ -320,8 +320,8 @@ nbtk_style_new (void)
  * Return the default NbtkStyle object. This includes the current theme (if
  * any).
  *
- * Returns: a #NbtkStyle object. This must not be freed or unref'd by
+ * Returns: (transfer none): a #NbtkStyle object. This must not be freed or
- * applications
+ * unref'd by applications
  */
 NbtkStyle *
 nbtk_style_get_default (void)
@@ -588,7 +588,7 @@ nbtk_style_get_ccss_query (NbtkStyle         *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/nbtk/nbtk-subtexture.c

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

src/nbtk/nbtk-texture-cache.c

@@ -169,7 +169,7 @@ nbtk_texture_cache_init (NbtkTextureCache *self)
  * Returns the default texture cache. This is owned by Nbtk and should not be
  * unreferenced or freed.
  *
- * Returns: a NbtkTextureCache
+ * Returns: (transfer none): a NbtkTextureCache
  */
 NbtkTextureCache*
 nbtk_texture_cache_get_default (void)
@@ -244,7 +244,7 @@ add_texture_to_cache (NbtkTextureCache     *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*
 nbtk_texture_cache_get_texture (NbtkTextureCache *self,
@@ -323,7 +323,7 @@ nbtk_texture_cache_get_texture (NbtkTextureCache *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*
 nbtk_texture_cache_get_actor (NbtkTextureCache *self,

src/nbtk/nbtk-texture-frame.c

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

src/nbtk/nbtk-widget.c

@@ -1125,7 +1125,7 @@ nbtk_widget_ensure_style (NbtkWidget *widget)
  * "border-image" CSS property. This function should normally only be used
  * by subclasses.
  *
- * Returns: #ClutterActor
+ * Returns: (transfer none): #ClutterActor
  */
 ClutterActor *
 nbtk_widget_get_border_image (NbtkWidget *actor)
@@ -1142,7 +1142,7 @@ nbtk_widget_get_border_image (NbtkWidget *actor)
  * "background-image" CSS property. This function should normally only be used
  * by subclasses.
  *
- * Returns: a #ClutterActor
+ * Returns: (transfer none): a #ClutterActor
  */
 ClutterActor *
 nbtk_widget_get_background_image (NbtkWidget *actor)