GNOME.org
 

[gnome-shell/shell-toolkit: 9/32] Add GObject Introspection annotations

commit f94eab803b5b7193720ac9b32f182271437cf90a
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.
    
    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           |    2 +-
 src/st/st-clipboard.c     |    4 ++--
 src/st/st-entry.c         |    4 ++--
 src/st/st-label.c         |    4 ++--
 src/st/st-scroll-bar.c    |    9 +++++++++
 src/st/st-scroll-view.c   |   16 ++++++++++++++++
 src/st/st-scroll-view.h   |    1 -
 src/st/st-scrollable.c    |    8 ++++++++
 src/st/st-stylable.c      |   20 ++++++++++----------
 src/st/st-style.c         |    6 +++---
 src/st/st-subtexture.c    |    2 +-
 src/st/st-texture-cache.c |    6 +++---
 src/st/st-texture-frame.c |    2 +-
 src/st/st-widget.c        |    4 ++--
 14 files changed, 60 insertions(+), 28 deletions(-)
---
diff --git a/src/st/st-bin.c b/src/st/st-bin.c
index 005ed6b..6ae322c 100644
--- a/src/st/st-bin.c
+++ b/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)
diff --git a/src/st/st-clipboard.c b/src/st/st-clipboard.c
index c6507c1..d166a86 100644
--- a/src/st/st-clipboard.c
+++ b/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
- * freed.
+ * Returns: (transfer none): a #StClipboard owned by St and must not be
+ * unrefferenced or freed.
  */
 StClipboard*
 st_clipboard_get_default (void)
diff --git a/src/st/st-entry.c b/src/st/st-entry.c
index 20151bf..7781691 100644
--- a/src/st/st-entry.c
+++ b/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
- * #StEntry and should not be unref'ed by the application.
+ * Returns: (transfer none): ethe #ClutterText used by #StEntry. The entry is
+ * owned by the #StEntry and should not be unref'ed by the application.
  */
 ClutterActor*
 st_entry_get_clutter_text (StEntry *entry)
diff --git a/src/st/st-label.c b/src/st/st-label.c
index bcfcac6..6d1151f 100644
--- a/src/st/st-label.c
+++ b/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
- * #StLabel and should not be unref'ed by the application.
+ * Returns: (transfer none): ethe #ClutterText used by #StLabel. The label
+ * is owned by the #StLabel and should not be unref'ed by the application.
  */
 ClutterActor*
 st_label_get_clutter_text (StLabel *label)
diff --git a/src/st/st-scroll-bar.c b/src/st/st-scroll-bar.c
index ad636df..414c6e6 100644
--- a/src/st/st-scroll-bar.c
+++ b/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)
 {
diff --git a/src/st/st-scroll-view.c b/src/st/st-scroll-view.c
index 8f4332f..c6c64b3 100644
--- a/src/st/st-scroll-view.c
+++ b/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)
 {
diff --git a/src/st/st-scroll-view.h b/src/st/st-scroll-view.h
index c2a3553..774fc05 100644
--- a/src/st/st-scroll-view.h
+++ b/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,
diff --git a/src/st/st-scrollable.c b/src/st/st-scrollable.c
index 1c3fc7b..384ac4b 100644
--- a/src/st/st-scrollable.c
+++ b/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,
diff --git a/src/st/st-stylable.c b/src/st/st-stylable.c
index 1af8788..6d23dee 100644
--- a/src/st/st-stylable.c
+++ b/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
- *   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 **
 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
- *   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 *
 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)
diff --git a/src/st/st-style.c b/src/st/st-style.c
index 15e74a6..3e9619a 100644
--- a/src/st/st-style.c
+++ b/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
- * applications
+ * Returns: (transfer none): a #StStyle object. This must not be freed or
+ * 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
  */
diff --git a/src/st/st-subtexture.c b/src/st/st-subtexture.c
index 7ea1fa4..1bcd896 100644
--- a/src/st/st-subtexture.c
+++ b/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)
diff --git a/src/st/st-texture-cache.c b/src/st/st-texture-cache.c
index 0cab32c..dea1bee 100644
--- a/src/st/st-texture-cache.c
+++ b/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,
diff --git a/src/st/st-texture-frame.c b/src/st/st-texture-frame.c
index 75d3430..9162169 100644
--- a/src/st/st-texture-frame.c
+++ b/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)
diff --git a/src/st/st-widget.c b/src/st/st-widget.c
index bcc4a2c..a27d9d0 100644
--- a/src/st/st-widget.c
+++ b/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)
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]