From f1f11f1e761256690f7c0c9fc3dd9620d9d28cfd Mon Sep 17 00:00:00 2001 From: "Owen W. Taylor" Date: Wed, 16 Sep 2009 19:07:23 -0400 Subject: [PATCH] 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 0bd1dabe9..03ad68cad 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 f10337224..393f69848 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 75925484b..5c6df2941 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 9cc762a63..e71efaca6 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 3763724af..1a4a63b85 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 2c678337d..321584498 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 32c992850..22919a847 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 0c07398e3..48e89574e 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 aed1e9eea..0e0ef9783 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 b3ca7fc2a..eefdaedbb 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 #GParamSpecs installed by @stylable. * - * Return value: an array of #GParamSpecs. Free it with - * g_free() when done. + * Return value: (transfer container) (array length=n_props): an array + * of #GParamSpecs. 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 f5eeb3ba0..4c3514097 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 4841dc803..019d2435d 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 10499bd77..97b85cfa2 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 6734cbac1..e37bf4b82 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 1542cecde..bc6cc9c68 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)