GNOME.org
 

[libgrss] Add lots of GObject Introspection annotations.

commit 4b1eda603a91a4a20d9141cf44ac684b3097fe1b
Author: Simon Kågedal Reimer <skagedal gmail com>
Date:   Tue Jul 9 21:42:49 2013 +0200

    Add lots of GObject Introspection annotations.
    
    Also fixes a bug in feed-channel.c:
    grss_feed_channel_get_cookies returns a GSList, not a GList.
    
    Signed-off-by: Roberto Guido <bob4job gmail com>

 src/feed-channel.c     |   19 +++++++++++--------
 src/feed-channel.h     |    2 +-
 src/feed-item.c        |   12 +++++++-----
 src/feed-parser.c      |    5 +++--
 src/feeds-group.c      |   12 +++++++-----
 src/feeds-pool.c       |    9 +++++----
 src/feeds-publisher.c  |   11 +++++++----
 src/feeds-store.c      |    8 ++++----
 src/feeds-subscriber.c |   14 ++++++++------
 9 files changed, 53 insertions(+), 39 deletions(-)
---
diff --git a/src/feed-channel.c b/src/feed-channel.c
index 61afa6b..e349204 100644
--- a/src/feed-channel.c
+++ b/src/feed-channel.c
@@ -640,7 +640,7 @@ grss_feed_channel_add_contributor (GrssFeedChannel *channel, gchar *contributor)
  *
  * Retrieves reference to the contributors of the @channel.
  *
- * Return value: list of contributors to the channel, or %NULL.
+ * Return value: (element-type utf8) (transfer none) list of contributors to the channel, or %NULL.
  */
 const GList*
 grss_feed_channel_get_contributors (GrssFeedChannel *channel)
@@ -668,11 +668,12 @@ grss_feed_channel_add_cookie (GrssFeedChannel *channel, SoupCookie *cookie)
  * @channel: a #GrssFeedChannel.
  *
  * Retrieves reference to the HTML cookies of the @channel.
- * Must be freed with g_list_free.
+ * The list and the individual cookies should all be freed after use.
+ * You can use soup_cookies_free.
  *
- * Return value: list of cookies to the channel, or %NULL.
+ * Return value: (element-type SoupCookie) (transfer full) list of cookies to the channel, or %NULL.
  */
-GList*
+GSList*
 grss_feed_channel_get_cookies (GrssFeedChannel *channel)
 {
        if (channel->priv->jar != NULL)
@@ -1029,8 +1030,9 @@ grss_feed_channel_fetch_async (GrssFeedChannel *channel, GAsyncReadyCallback cal
  * Utility to fetch and populate a #GrssFeedChannel, and retrieve all its
  * items.
  *
- * Return value: a GList of #GrssFeedItem, to be completely unreferenced and
- * freed when no longer in use, or %NULL if an error occurs.
+ * Return value: (element-type GrssFeedItem) (transfer full) a GList
+ * of #GrssFeedItem, to be completely unreferenced and freed when no
+ * longer in use, or %NULL if an error occurs.
  */
 GList*
 grss_feed_channel_fetch_all (GrssFeedChannel *channel, GError **error)
@@ -1143,8 +1145,9 @@ grss_feed_channel_fetch_all_async (GrssFeedChannel *channel, GAsyncReadyCallback
  * Finalizes an asyncronous operation started with
  * grss_feed_channel_fetch_all_async().
  *
- * Return value: list of items fetched from the #GrssFeedChannel, or %NULL if
- * @error is set. The list (and contained items) is freed at the end of the
+ * Return value: (element-type GrssFeedItem) (transfer none) list of
+ * items fetched from the #GrssFeedChannel, or %NULL if @error is
+ * set. The list (and contained items) is freed at the end of the
  * callback
  */
 GList*
diff --git a/src/feed-channel.h b/src/feed-channel.h
index 970c4d4..00828ca 100644
--- a/src/feed-channel.h
+++ b/src/feed-channel.h
@@ -78,7 +78,7 @@ const gchar*          grss_feed_channel_get_editor            (GrssFeedChannel *channel);
 void                   grss_feed_channel_add_contributor       (GrssFeedChannel *channel, gchar 
*contributor);
 const GList*           grss_feed_channel_get_contributors      (GrssFeedChannel *channel);
 void                   grss_feed_channel_add_cookie            (GrssFeedChannel *channel, SoupCookie 
*cookie);
-GList*                 grss_feed_channel_get_cookies           (GrssFeedChannel *channel);
+GSList*                        grss_feed_channel_get_cookies           (GrssFeedChannel *channel);
 void                   grss_feed_channel_set_webmaster         (GrssFeedChannel *channel, gchar *webmaster);
 const gchar*           grss_feed_channel_get_webmaster         (GrssFeedChannel *channel);
 void                   grss_feed_channel_set_generator         (GrssFeedChannel *channel, gchar *generator);
diff --git a/src/feed-item.c b/src/feed-item.c
index baf837b..212ef9a 100644
--- a/src/feed-item.c
+++ b/src/feed-item.c
@@ -147,7 +147,7 @@ grss_feed_item_new (GrssFeedChannel *parent)
  *
  * Retrieves the feed from which the item belongs.
  *
- * Return value: the parent feed, as set in grss_feed_item_new().
+ * Return value: (transfer none) the parent feed, as set in grss_feed_item_new().
  */
 GrssFeedChannel*
 grss_feed_item_get_parent (GrssFeedItem *item)
@@ -283,8 +283,8 @@ grss_feed_item_add_category (GrssFeedItem *item, gchar *category)
  *
  * Retrieves list of categories assigned to the @item.
  *
- * Return value: list of strings, one for assigned category. Do not free or
- * modify this list.
+ * Return value: (element-type utf8) (transfer none) list of strings,
+ * one for assigned category. Do not free or modify this list.
  */
 const GList*
 grss_feed_item_get_categories (GrssFeedItem *item)
@@ -465,7 +465,8 @@ grss_feed_item_add_contributor (GrssFeedItem *item, gchar *contributor)
  *
  * Retrieves contributors for @item.
  *
- * Return value: list of contributors to the item.
+ * Return value: (element-type utf8) (transfer none) list of
+ * contributors to the item.
  */
 const GList*
 grss_feed_item_get_contributors (GrssFeedItem *item)
@@ -603,7 +604,8 @@ grss_feed_item_add_enclosure (GrssFeedItem *item, GrssFeedEnclosure *enclosure)
  *
  * Retrieves the list of enclosures added with grss_feed_item_add_enclosure().
  *
- * Return value: a list of #GrssFeedEnclosure. This is a direct reference to the
+ * Return value: (element-type GrssFeedEnclosure) (transfer none) a
+ * list of #GrssFeedEnclosure. This is a direct reference to the
  * internal list, do not free or modify it.
  */
 const GList*
diff --git a/src/feed-parser.c b/src/feed-parser.c
index a30bfe8..dbc3245 100644
--- a/src/feed-parser.c
+++ b/src/feed-parser.c
@@ -159,8 +159,9 @@ retrieve_feed_handler (GrssFeedParser *parser, xmlDocPtr doc, xmlNodePtr cur)
  * Parses the given XML @doc, belonging to the given @feed, to obtain a list
  * of #GrssFeedItem.
  *
- * Return value: a list of #GrssFeedItem, to be freed when no longer in use, or
- * NULL if an error occours and @error is set.
+ * Return value: (element-type GrssFeedItem) (transfer full) a list of
+ * #GrssFeedItem, to be freed when no longer in use, or NULL if an
+ * error occours and @error is set.
  */
 GList*
 grss_feed_parser_parse (GrssFeedParser *parser, GrssFeedChannel *feed, xmlDocPtr doc, GError **error)
diff --git a/src/feeds-group.c b/src/feeds-group.c
index 12eadf8..9931562 100644
--- a/src/feeds-group.c
+++ b/src/feeds-group.c
@@ -139,8 +139,9 @@ retrieve_group_handler (GrssFeedsGroup *group, xmlDocPtr doc, xmlNodePtr cur)
  *
  * Returns the list of supported file formats.
  *
- * Return value: a list of constant strings with names of supported formats. The
- * list must be freed when no longer used
+ * Return value: (element-type utf8) (transfer full) a list of
+ * constant strings with names of supported formats. The list must be
+ * freed when no longer used
  */
 GList*
 grss_feeds_group_get_formats (GrssFeedsGroup *group)
@@ -169,8 +170,9 @@ grss_feeds_group_get_formats (GrssFeedsGroup *group)
  *
  * Parses the given file to obtain list of listed feeds.
  *
- * Return value: a list of #GrssFeedChannels, or NULL if an error occours and
- * @error is set.
+ * Return value: (element-type GrssFeedChannel) (transfer full) a list
+ * of #GrssFeedChannels, or NULL if an error occours and @error is
+ * set.
  */
 GList*
 grss_feeds_group_parse_file (GrssFeedsGroup *group, const gchar *path, GError **error)
@@ -227,7 +229,7 @@ grss_feeds_group_parse_file (GrssFeedsGroup *group, const gchar *path, GError **
 /**
  * grss_feeds_group_export_file:
  * @group: a #GrssFeedsGroup.
- * @channels: list of #GrssFeedChannels.
+ * @channels: (element-type GrssFeedChannel) list of #GrssFeedChannels.
  * @format: string rappresenting the desired export format, as returnes by
  *          grss_feeds_group_get_formats().
  * @uri: URI of the file to write.
diff --git a/src/feeds-pool.c b/src/feeds-pool.c
index 83b05cf..2cd8574 100644
--- a/src/feeds-pool.c
+++ b/src/feeds-pool.c
@@ -191,7 +191,7 @@ create_listened (GrssFeedsPool *pool, GList *feeds)
 /**
  * grss_feeds_pool_listen:
  * @pool: a #GrssFeedsPool.
- * @feeds: a list of #GrssFeedChannel.
+ * @feeds: (element-type GrssFeedChannel) a list of #GrssFeedChannel.
  *
  * To set the list of feeds to be managed by the pool. The previous list, if
  * any, is invalidated. After invokation to the function, grss_feeds_pool_switch()
@@ -221,8 +221,9 @@ grss_feeds_pool_listen (GrssFeedsPool *pool, GList *feeds)
  * time and resources consuming task: if you only need to know how many feeds
  * are currently handled, check grss_feeds_pool_get_listened_num().
  *
- * Return value: a list of #GrssFeedChannel, to be freed with g_list_free() when
- * no longer in use. Do not modify elements found in this list.
+ * Return value: (element-type GrssFeedChannel) (transfer container) a
+ * list of #GrssFeedChannel, to be freed with g_list_free() when no
+ * longer in use. Do not modify elements found in this list.
  */
 GList*
 grss_feeds_pool_get_listened (GrssFeedsPool *pool)
@@ -366,7 +367,7 @@ grss_feeds_pool_switch (GrssFeedsPool *pool, gboolean run)
  *
  * To access the internal #SoupSession used by the @pool to fetch items.
  *
- * Return value: istance of #SoupSession. Do not free it.
+ * Return value: (transfer none) instance of #SoupSession. Do not free it.
  */
 SoupSession*
 grss_feeds_pool_get_session (GrssFeedsPool *pool)
diff --git a/src/feeds-publisher.c b/src/feeds-publisher.c
index 29eb4c1..191c91a 100644
--- a/src/feeds-publisher.c
+++ b/src/feeds-publisher.c
@@ -227,7 +227,8 @@ grss_feeds_publisher_new ()
  * grss_feeds_publisher_format_content:
  * @pub: a #GrssFeedsPublisher.
  * @channel: the #GrssFeedChannel to dump in the file.
- * @items: list of #GrssFeedItems to be added in the feed.
+ * @items: (element-type GrssFeedItem) list of #GrssFeedItems to be
+ *         added in the feed.
  * @error: if an error occourred, %NULL is returned and this is filled with the
  *         message.
  * 
@@ -492,7 +493,8 @@ feed_required_by_web_cb (SoupServer *server, SoupMessage *msg, const char *path,
  * grss_feeds_publisher_publish_web:
  * @pub: a #GrssFeedsPublisher.
  * @channel: the #GrssFeedChannel to dump in the file.
- * @items: list of #GrssFeedItems to be added in the feed.
+ * @items: (element-type GrssFeedItem) list of #GrssFeedItems to be
+ *         added in the feed.
  * @id: name used in the external URL of the feed.
  * @error: if an error occourred, %FALSE is returned and this is filled with the
  *         message.
@@ -528,7 +530,8 @@ grss_feeds_publisher_publish_web (GrssFeedsPublisher *pub, GrssFeedChannel *chan
  * grss_feeds_publisher_publish_file:
  * @pub: a #GrssFeedsPublisher.
  * @channel: the #GrssFeedChannel to dump in the file.
- * @items: list of #GrssFeedItems to be added in the feed.
+ * @items: (element-type GrssFeedItem) list of #GrssFeedItems to be
+ * added in the feed.
  * @uri: URI of the file to write. The full path must exists.
  * @error: if an error occourred, %FALSE is returned and this is filled with the
  *         message.
@@ -906,7 +909,7 @@ grss_feeds_publisher_hub_set_port (GrssFeedsPublisher *pub, int port)
 /**
  * grss_feeds_publisher_hub_set_topics:
  * @pub: a #GrssFeedsPublisher.
- * @topics: a list of #GrssFeedChannels.
+ * @topics: (element-type GrssFeedChannel) a list of #GrssFeedChannels.
  *
  * To define a list of valid "topics" for which the #GrssFeedsPublisher will
  * deliver contents. Sources of those channels, as retrieved by
diff --git a/src/feeds-store.c b/src/feeds-store.c
index 846bf44..cb99586 100644
--- a/src/feeds-store.c
+++ b/src/feeds-store.c
@@ -59,8 +59,8 @@ grss_feeds_store_init (GrssFeedsStore *node)
  *
  * To retrieve list of feeds permanently saved into the store.
  *
- * Return value: list of #GrssFeedChannel found in the @store. Do not modify or
- * free it.
+ * Return value: (element-type GrssFeedChannel) (transfer none) list
+ * of #GrssFeedChannel found in the @store. Do not modify or free it.
  */
 GList*
 grss_feeds_store_get_channels (GrssFeedsStore *store)
@@ -76,8 +76,8 @@ grss_feeds_store_get_channels (GrssFeedsStore *store)
  * To retrieve list of items saved into the store, assigned to the given
  * @channel.
  *
- * Return value: list of #GrssFeedItem found in the @store. Do not modify or free
- * it.
+ * Return value: (element-type GrssFeedItem) (transfer none) list of
+ * #GrssFeedItem found in the @store. Do not modify or free it.
  */
 GList*
 grss_feeds_store_get_items_by_channel (GrssFeedsStore *store, GrssFeedChannel *channel)
diff --git a/src/feeds-subscriber.c b/src/feeds-subscriber.c
index eed970e..563be3f 100644
--- a/src/feeds-subscriber.c
+++ b/src/feeds-subscriber.c
@@ -251,7 +251,7 @@ create_listened (GrssFeedsSubscriber *sub, GList *feeds)
 /**
  * grss_feeds_subscriber_listen:
  * @sub: a #GrssFeedsSubscriber.
- * @feeds: a list of #GrssFeedChannel.
+ * @feeds: (element-type GrssFeedChannel) a list of #GrssFeedChannel.
  *
  * To set the list of feeds to be managed by @sub. The previous list, if any,
  * is invalidated. After invokation to the function, grss_feeds_subscriber_switch()
@@ -275,8 +275,9 @@ grss_feeds_subscriber_listen (GrssFeedsSubscriber *sub, GList *feeds)
  *
  * Returns the list of feeds currently managed by @sub.
  *
- * Return value: a list of #GrssFeedChannel, to be freed with g_list_free() when
- * no longer in use. Do not modify elements found in this list.
+ * Return value: (element-type GrssFeedChannel) (transfer container) a
+ * list of #GrssFeedChannel, to be freed with g_list_free() when no
+ * longer in use. Do not modify elements found in this list.
  */
 GList*
 grss_feeds_subscriber_get_listened (GrssFeedsSubscriber *sub)
@@ -621,8 +622,8 @@ grss_feeds_subscriber_switch (GrssFeedsSubscriber *sub, gboolean run)
  * external events. It is often required by #GrssFeedsSubscriberHandlers while
  * subscribing contents to specify the local endpoint for communications.
  *
- * Return value: the #GInetAddress used by @sub, or %NULL if the
- * #GrssFeedsSubscriber is switched off.
+ * Return value: (transfer none) the #GInetAddress used by @sub, or
+ * %NULL if the #GrssFeedsSubscriber is switched off.
  */
 GInetAddress*
 grss_feeds_subscriber_get_address (GrssFeedsSubscriber *sub)
@@ -653,7 +654,8 @@ grss_feeds_subscriber_get_port (GrssFeedsSubscriber *sub)
  * To obtain the internal #SoupSession of a #GrssFeedsSubscriber, so to re-use
  * it in #GrssFeedsSubscriberHandlers or similar tasks.
  * 
- * Return value: the #SoupSession used by the provided #GrssFeedsSubscriber.
+ * Return value: (transfer none) the #SoupSession used by the provided
+ * #GrssFeedsSubscriber.
  */
 SoupSession*
 grss_feeds_subscriber_get_session (GrssFeedsSubscriber *sub)
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]