GNOME.org
 

[gnome-shell/nbtk-introduction] Add GObject Introspection annotations

commit f1f11f1e761256690f7c0c9fc3dd9620d9d28cfd
Author: Owen W. Taylor <otaylor fishsoup net>
Date:   Wed Sep 16 19:07:23 2009 -0400

    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           |    2 +-
 src/nbtk/nbtk-clipboard.c     |    6 +++---
 src/nbtk/nbtk-clipboard.h     |    2 +-
 src/nbtk/nbtk-entry.c         |    4 ++--
 src/nbtk/nbtk-label.c         |    4 ++--
 src/nbtk/nbtk-scroll-bar.c    |    9 +++++++++
 src/nbtk/nbtk-scroll-view.c   |   16 ++++++++++++++++
 src/nbtk/nbtk-scroll-view.h   |    1 -
 src/nbtk/nbtk-scrollable.c    |    8 ++++++++
 src/nbtk/nbtk-stylable.c      |   20 ++++++++++----------
 src/nbtk/nbtk-style.c         |    6 +++---
 src/nbtk/nbtk-subtexture.c    |    2 +-
 src/nbtk/nbtk-texture-cache.c |    6 +++---
 src/nbtk/nbtk-texture-frame.c |    2 +-
 src/nbtk/nbtk-widget.c        |    4 ++--
 15 files changed, 62 insertions(+), 30 deletions(-)
---
diff --git a/src/nbtk/nbtk-bin.c b/src/nbtk/nbtk-bin.c
index 0bd1dab..03ad68c 100644
--- a/src/nbtk/nbtk-bin.c
+++ b/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)
diff --git a/src/nbtk/nbtk-clipboard.c b/src/nbtk/nbtk-clipboard.c
index f103372..393f698 100644
--- a/src/nbtk/nbtk-clipboard.c
+++ b/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
- * freed.
+ * Returns: (transfer none): a #NbtkClipboard owned by Nbtk and must not be
+ * unrefferenced or freed.
  */
 NbtkClipboard*
-nbtk_clipboard_get_default ()
+nbtk_clipboard_get_default (void)
 {
   static NbtkClipboard *default_clipboard = NULL;
 
diff --git a/src/nbtk/nbtk-clipboard.h b/src/nbtk/nbtk-clipboard.h
index 7592548..5c6df29 100644
--- a/src/nbtk/nbtk-clipboard.h
+++ b/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);
 
diff --git a/src/nbtk/nbtk-entry.c b/src/nbtk/nbtk-entry.c
index 9cc762a..e71efac 100644
--- a/src/nbtk/nbtk-entry.c
+++ b/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
- * #NbtkEntry and should not be unref'ed by the application.
+ * Returns: (transfer none): ethe #ClutterText used by #NbtkEntry. The entry is
+ * owned by the #NbtkEntry and should not be unref'ed by the application.
  */
 ClutterActor*
 nbtk_entry_get_clutter_text (NbtkEntry *entry)
diff --git a/src/nbtk/nbtk-label.c b/src/nbtk/nbtk-label.c
index 3763724..1a4a63b 100644
--- a/src/nbtk/nbtk-label.c
+++ b/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
- * #NbtkLabel and should not be unref'ed by the application.
+ * Returns: (transfer none): ethe #ClutterText used by #NbtkLabel. The label
+ * is owned by the #NbtkLabel and should not be unref'ed by the application.
  */
 ClutterActor*
 nbtk_label_get_clutter_text (NbtkLabel *label)
diff --git a/src/nbtk/nbtk-scroll-bar.c b/src/nbtk/nbtk-scroll-bar.c
index 2c67833..3215844 100644
--- a/src/nbtk/nbtk-scroll-bar.c
+++ b/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)
 {
diff --git a/src/nbtk/nbtk-scroll-view.c b/src/nbtk/nbtk-scroll-view.c
index 32c9928..22919a8 100644
--- a/src/nbtk/nbtk-scroll-view.c
+++ b/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)
 {
diff --git a/src/nbtk/nbtk-scroll-view.h b/src/nbtk/nbtk-scroll-view.h
index 0c07398..48e8957 100644
--- a/src/nbtk/nbtk-scroll-view.h
+++ b/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,
diff --git a/src/nbtk/nbtk-scrollable.c b/src/nbtk/nbtk-scrollable.c
index aed1e9e..0e0ef97 100644
--- a/src/nbtk/nbtk-scrollable.c
+++ b/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,
diff --git a/src/nbtk/nbtk-stylable.c b/src/nbtk/nbtk-stylable.c
index b3ca7fc..eefdaed 100644
--- a/src/nbtk/nbtk-stylable.c
+++ b/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
- *   g_free() when done.
+ * Return value: (transfer container) (array length=n_props): an array
+ *  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
- *   no property with that name was found
+ * Return value: (transfer none): a #GParamSpec for the given property,
+ *   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)
diff --git a/src/nbtk/nbtk-style.c b/src/nbtk/nbtk-style.c
index f5eeb3b..4c35140 100644
--- a/src/nbtk/nbtk-style.c
+++ b/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
- * applications
+ * Returns: (transfer none): a #NbtkStyle object. This must not be freed or
+ * 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
  */
diff --git a/src/nbtk/nbtk-subtexture.c b/src/nbtk/nbtk-subtexture.c
index 4841dc8..019d243 100644
--- a/src/nbtk/nbtk-subtexture.c
+++ b/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)
diff --git a/src/nbtk/nbtk-texture-cache.c b/src/nbtk/nbtk-texture-cache.c
index 10499bd..97b85cf 100644
--- a/src/nbtk/nbtk-texture-cache.c
+++ b/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,
diff --git a/src/nbtk/nbtk-texture-frame.c b/src/nbtk/nbtk-texture-frame.c
index 6734cba..e37bf4b 100644
--- a/src/nbtk/nbtk-texture-frame.c
+++ b/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)
diff --git a/src/nbtk/nbtk-widget.c b/src/nbtk/nbtk-widget.c
index 1542cec..bc6cc9c 100644
--- a/src/nbtk/nbtk-widget.c
+++ b/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)
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]