[libgrss] Minor improvements in documentation

From: Roberto Guido <rguido src gnome org>
To: commits-list gnome org
Cc:
Subject: [libgrss] Minor improvements in documentation
Date: Sat, 3 Mar 2012 20:28:36 +0000 (UTC)
commit 28047919a9dab9c76b9ce611dfbcb7f3c86ba7b0
Author: Roberto Guido <bob4job gmail com>
Date:   Sat Mar 3 21:27:58 2012 +0100

    Minor improvements in documentation

 src/feed-channel.c     |  315 ++++++++++++++++++++++++------------------------
 src/feed-enclosure.c   |   42 +++---
 src/feed-item.c        |  195 +++++++++++++++---------------
 src/feed-parser.c      |   16 ++--
 src/feeds-group.c      |   43 ++++---
 src/feeds-pool.c       |   48 ++++----
 src/feeds-publisher.c  |   80 ++++++------
 src/feeds-store.c      |   38 +++---
 src/feeds-subscriber.c |   59 +++++-----
 9 files changed, 426 insertions(+), 410 deletions(-)
---
diff --git a/src/feed-channel.c b/src/feed-channel.c
index c370bc7..7dac065 100644
--- a/src/feed-channel.c
+++ b/src/feed-channel.c
@@ -29,7 +29,8 @@
  * SECTION: feed-channel
  * @short_description: a feed
  *
- * #GrssFeedChannel rappresents a single feed which may be fetched and parsed
+ * #GrssFeedChannel rappresents a single feed which may be fetched and parsed.
+ * It mostly is a passive container for attributes.
  */
 
 typedef struct {
@@ -130,9 +131,9 @@ grss_feed_channel_init (GrssFeedChannel *node)
 /**
  * grss_feed_channel_new:
  *
- * Allocates a new #GrssFeedChannel
+ * Allocates a new #GrssFeedChannel.
  *
- * Return value: a #GrssFeedChannel
+ * Return value: a #GrssFeedChannel.
  */
 GrssFeedChannel*
 grss_feed_channel_new ()
@@ -142,11 +143,11 @@ grss_feed_channel_new ()
 
 /**
  * grss_feed_channel_new_with_source:
- * @source: URL of the feed
+ * @source: URL of the feed.
  *
- * Allocates a new #GrssFeedChannel and assign it the given remote source
+ * Allocates a new #GrssFeedChannel and assign it the given remote source.
  *
- * Return value: a #GrssFeedChannel
+ * Return value: a #GrssFeedChannel.
  */
 GrssFeedChannel*
 grss_feed_channel_new_with_source (gchar *source)
@@ -160,15 +161,15 @@ grss_feed_channel_new_with_source (gchar *source)
 
 /**
  * grss_feed_channel_new_from_file:
- * @path: path of the file to parse
+ * @path: path of the file to parse.
  * @error: if an error occourred, %NULL is returned and this is filled with the
- *         message
+ *         message.
  *
  * Allocates a new #GrssFeedChannel and init it with contents found in specified
- * file
+ * file.
  *
  * Return value: a #GrssFeedChannel, or %NULL if the file in @path is not a
- * valid document
+ * valid document.
  */
 GrssFeedChannel*
 grss_feed_channel_new_from_file (const gchar *path, GError **error)
@@ -218,10 +219,11 @@ grss_feed_channel_new_from_file (const gchar *path, GError **error)
 
 /**
  * grss_feed_channel_set_format:
- * @channel: a #GrssFeedChannel
- * @format: format of the file, such as "application/atom+xml" or "application/rss+xml"
+ * @channel: a #GrssFeedChannel.
+ * @format: format of the file, such as "application/atom+xml" or
+ * "application/rss+xml".
  *
- * To assign a file format to the feed
+ * To assign a file format to the feed.
  */
 void
 grss_feed_channel_set_format (GrssFeedChannel *channel, gchar *format)
@@ -232,11 +234,11 @@ grss_feed_channel_set_format (GrssFeedChannel *channel, gchar *format)
 
 /**
  * grss_feed_channel_get_format:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  *
- * Retrieves the file format of @channel
+ * Retrieves the file format of @channel.
  *
- * Return value: file format of channel
+ * Return value: file format of channel.
  */
 const gchar*
 grss_feed_channel_get_format (GrssFeedChannel *channel)
@@ -246,10 +248,10 @@ grss_feed_channel_get_format (GrssFeedChannel *channel)
 
 /**
  * grss_feed_channel_set_source:
- * @channel: a #GrssFeedChannel
- * @source: URL of the feed
+ * @channel: a #GrssFeedChannel.
+ * @source: URL of the feed.
  *
- * To assign the URL where to fetch the feed
+ * To assign the URL where to fetch the feed.
  */
 void
 grss_feed_channel_set_source (GrssFeedChannel *channel, gchar *source)
@@ -263,11 +265,11 @@ grss_feed_channel_set_source (GrssFeedChannel *channel, gchar *source)
 
 /**
  * grss_feed_channel_get_source:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  *
- * Retrieves URL where to fetch the @channel
+ * Retrieves URL where to fetch the @channel.
  *
- * Return value: URL of the channel
+ * Return value: URL of the channel.
  */
 const gchar*
 grss_feed_channel_get_source (GrssFeedChannel *channel)
@@ -277,10 +279,10 @@ grss_feed_channel_get_source (GrssFeedChannel *channel)
 
 /**
  * grss_feed_channel_set_title:
- * @channel: a #GrssFeedChannel
- * @title: title of the feed
+ * @channel: a #GrssFeedChannel.
+ * @title: title of the feed.
  *
- * To set a title to the @channel
+ * To set a title to the @channel.
  */
 void
 grss_feed_channel_set_title (GrssFeedChannel *channel, gchar *title)
@@ -291,11 +293,11 @@ grss_feed_channel_set_title (GrssFeedChannel *channel, gchar *title)
 
 /**
  * grss_feed_channel_get_title:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  *
- * Retrieves title of the @channel
+ * Retrieves title of the @channel.
  *
- * Return value: title of the feed, or NULL
+ * Return value: title of the feed, or %NULL.
  */
 const gchar*
 grss_feed_channel_get_title (GrssFeedChannel *channel)
@@ -305,10 +307,10 @@ grss_feed_channel_get_title (GrssFeedChannel *channel)
 
 /**
  * grss_feed_channel_set_homepage:
- * @channel: a #GrssFeedChannel
- * @homepage: homepage for the main website
+ * @channel: a #GrssFeedChannel.
+ * @homepage: homepage for the main website.
  *
- * To set the homepage of the site the @channel belongs
+ * To set the homepage of the site the @channel belongs.
  */
 void
 grss_feed_channel_set_homepage (GrssFeedChannel *channel, gchar *homepage)
@@ -319,11 +321,11 @@ grss_feed_channel_set_homepage (GrssFeedChannel *channel, gchar *homepage)
 
 /**
  * grss_feed_channel_get_homepage:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  *
- * Retrieves the homepage of the site for which @channel is the feed
+ * Retrieves the homepage of the site for which @channel is the feed.
  *
- * Return value: reference homepage of the feed, or NULL
+ * Return value: reference homepage of the feed, or %NULL.
  */
 const gchar*
 grss_feed_channel_get_homepage (GrssFeedChannel *channel)
@@ -333,10 +335,10 @@ grss_feed_channel_get_homepage (GrssFeedChannel *channel)
 
 /**
  * grss_feed_channel_set_description:
- * @channel: a #GrssFeedChannel
- * @description: description of the feed
+ * @channel: a #GrssFeedChannel.
+ * @description: description of the feed.
  *
- * To set the description of @channel
+ * To set the description of @channel.
  */
 void
 grss_feed_channel_set_description (GrssFeedChannel *channel, gchar *description)
@@ -347,11 +349,11 @@ grss_feed_channel_set_description (GrssFeedChannel *channel, gchar *description)
 
 /**
  * grss_feed_channel_get_description:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  *
- * Retrieves the description of @channel
+ * Retrieves the description of @channel.
  *
- * Return value: description of the feed, or NULL
+ * Return value: description of the feed, or %NULL.
  */
 const gchar*
 grss_feed_channel_get_description (GrssFeedChannel *channel)
@@ -361,10 +363,10 @@ grss_feed_channel_get_description (GrssFeedChannel *channel)
 
 /**
  * grss_feed_channel_set_image:
- * @channel: a #GrssFeedChannel
- * @image: URL of the image
+ * @channel: a #GrssFeedChannel.
+ * @image: URL of the image.
  *
- * To set a rappresentative image to @channel
+ * To set a rappresentative image to @channel.
  */
 void
 grss_feed_channel_set_image (GrssFeedChannel *channel, gchar *image)
@@ -375,11 +377,11 @@ grss_feed_channel_set_image (GrssFeedChannel *channel, gchar *image)
 
 /**
  * grss_feed_channel_get_image:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  *
- * Retrieves the URL of the image assigned to the channel
+ * Retrieves the URL of the image assigned to the channel.
  *
- * Return value: URL of the image, or NULL
+ * Return value: URL of the image, or %NULL.
  */
 const gchar*
 grss_feed_channel_get_image (GrssFeedChannel *channel)
@@ -389,10 +391,10 @@ grss_feed_channel_get_image (GrssFeedChannel *channel)
 
 /**
  * grss_feed_channel_set_icon:
- * @channel: a #GrssFeedChannel
- * @icon: URL where to retrieve the favicon
+ * @channel: a #GrssFeedChannel.
+ * @icon: URL where to retrieve the favicon.
  *
- * To set the URL of the icon rappresenting @channel
+ * To set the URL of the icon rappresenting @channel.
  */
 void
 grss_feed_channel_set_icon (GrssFeedChannel *channel, gchar *icon)
@@ -403,12 +405,12 @@ grss_feed_channel_set_icon (GrssFeedChannel *channel, gchar *icon)
 
 /**
  * grss_feed_channel_get_icon:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  *
  * Retrieves URL of the favicon of the channel (and/or the website for which
- * this is the feed)
+ * this is the feed).
  *
- * Return value: URL of the favicon, or NULL
+ * Return value: URL of the favicon, or %NULL.
  */
 const gchar*
 grss_feed_channel_get_icon (GrssFeedChannel *channel)
@@ -418,10 +420,10 @@ grss_feed_channel_get_icon (GrssFeedChannel *channel)
 
 /**
  * grss_feed_channel_set_language:
- * @channel: a #GrssFeedChannel
- * @language: string holding the language of the feed
+ * @channel: a #GrssFeedChannel.
+ * @language: string holding the language of the feed.
  *
- * To set the language of @channel
+ * To set the language of @channel.
  */
 void
 grss_feed_channel_set_language (GrssFeedChannel *channel, gchar *language)
@@ -432,11 +434,11 @@ grss_feed_channel_set_language (GrssFeedChannel *channel, gchar *language)
 
 /**
  * grss_feed_channel_get_language:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  *
- * Retrieves the language of the @channel
+ * Retrieves the language of the @channel.
  *
- * Return value: string rappresenting the language of channel
+ * Return value: string rappresenting the language of channel, or %NULL.
  */
 const gchar*
 grss_feed_channel_get_language (GrssFeedChannel *channel)
@@ -446,10 +448,10 @@ grss_feed_channel_get_language (GrssFeedChannel *channel)
 
 /**
  * grss_feed_channel_set_category:
- * @channel: a #GrssFeedChannel
- * @category: category of the feed
+ * @channel: a #GrssFeedChannel.
+ * @category: category of the feed.
  *
- * To set the category of the @channel
+ * To set the category of the @channel.
  */
 void
 grss_feed_channel_set_category (GrssFeedChannel *channel, gchar *category)
@@ -460,11 +462,11 @@ grss_feed_channel_set_category (GrssFeedChannel *channel, gchar *category)
 
 /**
  * grss_feed_channel_get_category:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  *
- * Retrieves category of the @channel
+ * Retrieves category of the @channel.
  *
- * Return value: category of the feed, or NULL
+ * Return value: category of the feed, or %NULL.
  */
 const gchar*
 grss_feed_channel_get_category (GrssFeedChannel *channel)
@@ -474,11 +476,11 @@ grss_feed_channel_get_category (GrssFeedChannel *channel)
 
 /**
  * grss_feed_channel_set_pubsubhub:
- * @channel: a #GrssFeedChannel
- * @hub: hub for the feed, or NULL
+ * @channel: a #GrssFeedChannel.
+ * @hub: hub for the feed, or %NULL.
  *
  * To set information about PubSubHubbub for the channel. To unset the hub,
- * pass %NULL as parameter
+ * pass %NULL as parameter.
  */
 void
 grss_feed_channel_set_pubsubhub (GrssFeedChannel *channel, gchar *hub)
@@ -491,13 +493,13 @@ grss_feed_channel_set_pubsubhub (GrssFeedChannel *channel, gchar *hub)
 
 /**
  * grss_feed_channel_get_pubsubhub:
- * @channel: a #GrssFeedChannel
- * @hub: location for the hub string, or NULL
+ * @channel: a #GrssFeedChannel.
+ * @hub: location for the hub string, or %NULL.
  *
- * Retrieves information about the PubSubHubbub hub of the channel
+ * Retrieves information about the PubSubHubbub hub of the channel.
  *
  * Return value: %TRUE if a valid PubSubHubbub hub has been set for the
- * @channel, %FALSE otherwise
+ * @channel, %FALSE otherwise.
  */
 gboolean
 grss_feed_channel_get_pubsubhub (GrssFeedChannel *channel, gchar **hub)
@@ -510,12 +512,12 @@ grss_feed_channel_get_pubsubhub (GrssFeedChannel *channel, gchar **hub)
 
 /**
  * grss_feed_channel_set_rsscloud:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  * @path: complete references of the URL where to register subscription, e.g.
- * http://example.com/rsscloudNotify
- * @protocol: type of protocol used for notifications
+ *        http://example.com/rsscloudNotify .
+ * @protocol: type of protocol used for notifications.
  *
- * To set information about RSSCloud notifications for the channel
+ * To set information about RSSCloud notifications for the channel.
  */
 void
 grss_feed_channel_set_rsscloud (GrssFeedChannel *channel, gchar *path, gchar *protocol)
@@ -531,14 +533,14 @@ grss_feed_channel_set_rsscloud (GrssFeedChannel *channel, gchar *path, gchar *pr
 
 /**
  * grss_feed_channel_get_rsscloud:
- * @channel: a #GrssFeedChannel
- * @path: location for the path string, or NULL
- * @protocol: location for the protocol string, or NULL
+ * @channel: a #GrssFeedChannel.
+ * @path: location for the path string, or %NULL.
+ * @protocol: location for the protocol string, or %NULL.
  *
- * Retrieves information about the RSSCloud coordinates of the channel
+ * Retrieves information about the RSSCloud coordinates of the channel.
  *
  * Return value: %TRUE if a valid RSSCloud path has been set for the
- * @channel, %FALSE otherwise
+ * @channel, %FALSE otherwise.
  */
 gboolean
 grss_feed_channel_get_rsscloud (GrssFeedChannel *channel, gchar **path, gchar **protocol)
@@ -553,10 +555,10 @@ grss_feed_channel_get_rsscloud (GrssFeedChannel *channel, gchar **path, gchar **
 
 /**
  * grss_feed_channel_set_copyright:
- * @channel: a #GrssFeedChannel
- * @copyright: copyright of the channel
+ * @channel: a #GrssFeedChannel.
+ * @copyright: copyright of the channel.
  *
- * To set the copyright of the feed
+ * To set the copyright of the feed.
  */
 void
 grss_feed_channel_set_copyright (GrssFeedChannel *channel, gchar *copyright)
@@ -567,11 +569,11 @@ grss_feed_channel_set_copyright (GrssFeedChannel *channel, gchar *copyright)
 
 /**
  * grss_feed_channel_get_copyright:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  *
- * Retrieves indications about the copyright
+ * Retrieves indications about the copyright.
  *
- * Return value: copyright of the @channel, or NULL
+ * Return value: copyright of the @channel, or %NULL.
  */
 const gchar*
 grss_feed_channel_get_copyright (GrssFeedChannel *channel)
@@ -581,10 +583,10 @@ grss_feed_channel_get_copyright (GrssFeedChannel *channel)
 
 /**
  * grss_feed_channel_set_editor:
- * @channel: a #GrssFeedChannel
- * @editor: editor of the feed
+ * @channel: a #GrssFeedChannel.
+ * @editor: editor of the feed.
  *
- * To set the editor of the @channel
+ * To set the editor of the @channel.
  */
 void
 grss_feed_channel_set_editor (GrssFeedChannel *channel, gchar *editor)
@@ -595,11 +597,11 @@ grss_feed_channel_set_editor (GrssFeedChannel *channel, gchar *editor)
 
 /**
  * grss_feed_channel_get_editor:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  *
- * Retrieves reference to the editor or the @channel
+ * Retrieves reference to the editor or the @channel.
  *
- * Return value: editor of the feed, or NULL
+ * Return value: editor of the feed, or %NULL.
  */
 const gchar*
 grss_feed_channel_get_editor (GrssFeedChannel *channel)
@@ -609,10 +611,10 @@ grss_feed_channel_get_editor (GrssFeedChannel *channel)
 
 /**
  * grss_feed_channel_add_contributor:
- * @channel: a #GrssFeedChannel
- * @contributor: contributor of the feed
+ * @channel: a #GrssFeedChannel.
+ * @contributor: contributor of the feed.
  *
- * To add a contributor to the @channel
+ * To add a contributor to the @channel.
  */
 void
 grss_feed_channel_add_contributor (GrssFeedChannel *channel, gchar *contributor)
@@ -629,11 +631,11 @@ grss_feed_channel_add_contributor (GrssFeedChannel *channel, gchar *contributor)
 
 /**
  * grss_feed_channel_get_contributors:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  *
- * Retrieves reference to the contributors of the @channel
+ * Retrieves reference to the contributors of the @channel.
  *
- * Return value: list of contributors to the channel, or NULL
+ * Return value: list of contributors to the channel, or %NULL.
  */
 const GList*
 grss_feed_channel_get_contributors (GrssFeedChannel *channel)
@@ -643,10 +645,10 @@ grss_feed_channel_get_contributors (GrssFeedChannel *channel)
 
 /**
  * grss_feed_channel_set_webmaster:
- * @channel: a #GrssFeedChannel
- * @webmaster: webmaster of the feed
+ * @channel: a #GrssFeedChannel.
+ * @webmaster: webmaster of the feed.
  *
- * To assign a webmaster to the @channel
+ * To assign a webmaster to the @channel.
  */
 void
 grss_feed_channel_set_webmaster (GrssFeedChannel *channel, gchar *webmaster)
@@ -657,11 +659,11 @@ grss_feed_channel_set_webmaster (GrssFeedChannel *channel, gchar *webmaster)
 
 /**
  * grss_feed_channel_get_webmaster:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  *
- * Retrieves reference to the webmaster of the feed
+ * Retrieves reference to the webmaster of the feed.
  *
- * Return value: webmaster of @channel, or NULL
+ * Return value: webmaster of @channel, or %NULL.
  */
 const gchar*
 grss_feed_channel_get_webmaster (GrssFeedChannel *channel)
@@ -671,10 +673,10 @@ grss_feed_channel_get_webmaster (GrssFeedChannel *channel)
 
 /**
  * grss_feed_channel_set_generator:
- * @channel: a #GrssFeedChannel
- * @generator: software generator of the feed
+ * @channel: a #GrssFeedChannel.
+ * @generator: software generator of the feed.
  *
- * To set information about the software generator of @channel
+ * To set information about the software generator of @channel.
  */
 void
 grss_feed_channel_set_generator (GrssFeedChannel *channel, gchar *generator)
@@ -685,11 +687,11 @@ grss_feed_channel_set_generator (GrssFeedChannel *channel, gchar *generator)
 
 /**
  * grss_feed_channel_get_generator:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  *
- * Retrieves information about the feed's software generator
+ * Retrieves information about the feed's software generator.
  *
- * Return value: generator of @channel, or NULL
+ * Return value: generator of @channel, or %NULL.
  */
 const gchar*
 grss_feed_channel_get_generator (GrssFeedChannel *channel)
@@ -699,10 +701,10 @@ grss_feed_channel_get_generator (GrssFeedChannel *channel)
 
 /**
  * grss_feed_channel_set_publish_time:
- * @channel: a #GrssFeedChannel
- * @publish: timestamp of publishing
+ * @channel: a #GrssFeedChannel.
+ * @publish: timestamp of publishing.
  *
- * To set the time of publishing for the feed
+ * To set the time of publishing for the feed.
  */
 void
 grss_feed_channel_set_publish_time (GrssFeedChannel *channel, time_t publish)
@@ -712,11 +714,11 @@ grss_feed_channel_set_publish_time (GrssFeedChannel *channel, time_t publish)
 
 /**
  * grss_feed_channel_get_publish_time:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  *
- * Retrieves the publishing time of @channel
+ * Retrieves the publishing time of @channel.
  *
- * Return value: time of feed's publish
+ * Return value: time of feed's publish.
  */
 time_t
 grss_feed_channel_get_publish_time (GrssFeedChannel *channel)
@@ -726,10 +728,10 @@ grss_feed_channel_get_publish_time (GrssFeedChannel *channel)
 
 /**
  * grss_feed_channel_set_update_time:
- * @channel: a #GrssFeedChannel
- * @update: update time of the feed
+ * @channel: a #GrssFeedChannel.
+ * @update: update time of the feed.
  *
- * To set the latest update time of @channel
+ * To set the latest update time of @channel.
  */
 void
 grss_feed_channel_set_update_time (GrssFeedChannel *channel, time_t update)
@@ -739,13 +741,13 @@ grss_feed_channel_set_update_time (GrssFeedChannel *channel, time_t update)
 
 /**
  * grss_feed_channel_get_update_time:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  *
- * Retrieves the update time of @channel
+ * Retrieves the update time of @channel.
  *
  * Return value: time of the feed's latest update. If this value was not set
  * (with grss_feed_channel_set_update_time()) returns
- * grss_feed_channel_get_publish_time()
+ * grss_feed_channel_get_publish_time().
  */
 time_t
 grss_feed_channel_get_update_time (GrssFeedChannel *channel)
@@ -755,10 +757,10 @@ grss_feed_channel_get_update_time (GrssFeedChannel *channel)
 
 /**
  * grss_feed_channel_set_update_interval:
- * @channel: a #GrssFeedChannel
- * @minutes: update interval, in minutes
+ * @channel: a #GrssFeedChannel.
+ * @minutes: update interval, in minutes.
  *
- * To set the update interval for @channel
+ * To set the update interval for @channel.
  */
 void
 grss_feed_channel_set_update_interval (GrssFeedChannel *channel, int minutes)
@@ -768,14 +770,14 @@ grss_feed_channel_set_update_interval (GrssFeedChannel *channel, int minutes)
 
 /**
  * grss_feed_channel_get_update_interval:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  *
  * Retrieves the update interval for the feed. Pay attention to the fact the
  * value can be unset, and the function returns 0: in this case the caller
  * must manually set a default update interval with
- * grss_feed_channel_set_update_interval()
+ * grss_feed_channel_set_update_interval().
  *
- * Return value: update interval for the @channel, in minutes
+ * Return value: update interval for the @channel, in minutes.
  */
 int
 grss_feed_channel_get_update_interval (GrssFeedChannel *channel)
@@ -825,17 +827,17 @@ quick_and_dirty_parse (GrssFeedChannel *channel, SoupMessage *msg, GList **save_
 
 /**
  * grss_feed_channel_fetch:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  * @error: if an error occourred, %FALSE is returned and this is filled with the
- *         message
+ *         message.
  *
  * Utility to fetch and populate a #GrssFeedChannel for the first time, and init
  * all his internal values. Only the source URL has to be set in @channel
  * (with grss_feed_channel_set_source()). Be aware this function is sync, do not
- * returns until the feed isn't downloaded and parsed
+ * returns until the feed isn't downloaded and parsed.
  *
  * Return value: %TRUE if the feed is correctly fetched and parsed, %FALSE
- * otherwise
+ * otherwise.
  */
 gboolean
 grss_feed_channel_fetch (GrssFeedChannel *channel, GError **error)
@@ -892,16 +894,16 @@ feed_downloaded (SoupSession *session, SoupMessage *msg, gpointer user_data) {
 
 /**
  * grss_feed_channel_fetch_finish:
- * @channel: a #GrssFeedChannel
- * @res: the #GAsyncResult passed to the callback
+ * @channel: a #GrssFeedChannel.
+ * @res: the #GAsyncResult passed to the callback.
  * @error: if an error occourred, %FALSE is returned and this is filled with the
- *         message
+ *         message.
  *
  * Finalizes an asyncronous operation started with
- * grss_feed_channel_fetch_async()
+ * grss_feed_channel_fetch_async().
  *
  * Return value: %TRUE if @channel informations have been successfully fetched,
- * %FALSE otherwise
+ * %FALSE otherwise.
  */
 gboolean
 grss_feed_channel_fetch_finish (GrssFeedChannel *channel, GAsyncResult *res, GError **error)
@@ -914,11 +916,11 @@ grss_feed_channel_fetch_finish (GrssFeedChannel *channel, GAsyncResult *res, GEr
 
 /**
  * grss_feed_channel_fetch_async:
- * @channel: a #GrssFeedChannel
- * @callback: function to invoke at the end of the download
- * @user_data: data passed to the callback
+ * @channel: a #GrssFeedChannel.
+ * @callback: function to invoke at the end of the download.
+ * @user_data: data passed to the callback.
  *
- * Similar to grss_feed_channel_fetch(), but asyncronous
+ * Similar to grss_feed_channel_fetch(), but asyncronous.
  */
 void
 grss_feed_channel_fetch_async (GrssFeedChannel *channel, GAsyncReadyCallback callback, gpointer user_data)
@@ -936,15 +938,15 @@ grss_feed_channel_fetch_async (GrssFeedChannel *channel, GAsyncReadyCallback cal
 
 /**
  * grss_feed_channel_fetch_all:
- * @channel: a #GrssFeedChannel
+ * @channel: a #GrssFeedChannel.
  * @error: if an error occourred, %NULL is returned and this is filled with the
- *         message
+ *         message.
  *
  * Utility to fetch and populate a #GrssFeedChannel, and retrieve all its
- * items
+ * items.
  *
  * Return value: a GList of #GrssFeedItem, to be completely unreferenced and
- * freed when no longer in use, or %NULL if an error occurs
+ * freed when no longer in use, or %NULL if an error occurs.
  */
 GList*
 grss_feed_channel_fetch_all (GrssFeedChannel *channel, GError **error)
@@ -1019,11 +1021,11 @@ feed_downloaded_return_items (SoupSession *session, SoupMessage *msg, gpointer u
 
 /**
  * grss_feed_channel_fetch_all_async:
- * @channel: a #GrssFeedChannel
- * @callback: function to invoke at the end of the download
- * @user_data: data passed to the callback
+ * @channel: a #GrssFeedChannel.
+ * @callback: function to invoke at the end of the download.
+ * @user_data: data passed to the callback.
  *
- * Similar to grss_feed_channel_fetch_all(), but asyncronous
+ * Similar to grss_feed_channel_fetch_all(), but asyncronous.
  */
 void
 grss_feed_channel_fetch_all_async (GrssFeedChannel *channel, GAsyncReadyCallback callback, gpointer user_data)
@@ -1041,14 +1043,17 @@ grss_feed_channel_fetch_all_async (GrssFeedChannel *channel, GAsyncReadyCallback
 
 /**
  * grss_feed_channel_fetch_all_finish:
- * @channel: a #GrssFeedChannel
- * @res: the #GAsyncResult passed to the callback
- * @error: if an error occourred, NULL is returned and this is filled with the message
+ * @channel: a #GrssFeedChannel.
+ * @res: the #GAsyncResult passed to the callback.
+ * @error: if an error occourred, %NULL is returned and this is filled with the
+ *         message.
  *
- * Finalizes an asyncronous operation started with grss_feed_channel_fetch_all_async()
+ * 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 callback
+ * 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
+ * callback
  */
 GList*
 grss_feed_channel_fetch_all_finish (GrssFeedChannel *channel, GAsyncResult *res, GError **error)
diff --git a/src/feed-enclosure.c b/src/feed-enclosure.c
index 46b1649..3ed0c71 100644
--- a/src/feed-enclosure.c
+++ b/src/feed-enclosure.c
@@ -27,9 +27,9 @@
  * SECTION: feed-enclosure
  * @short_description: a component attached to an item
  *
- * #GrssFeedEnclosure describes an external element embedded into a #GrssFeedItem: it
- * may be an image, a video of other kind of file to be presented with the
- * parent item
+ * #GrssFeedEnclosure describes an external element embedded into a
+ * #GrssFeedItem: it may be an image, a video of other kind of file to be
+ * presented with the parent item.
  */
 
 struct _GrssFeedEnclosurePrivate {
@@ -67,11 +67,11 @@ static void grss_feed_enclosure_init (GrssFeedEnclosure *node)
 
 /**
  * grss_feed_enclosure_new:
- * @url: URL of the external element
+ * @url: URL of the external element.
  *
- * Allocates a new #GrssFeedEnclosure, to be downloaded separately
+ * Allocates a new #GrssFeedEnclosure, to be downloaded separately.
  *
- * Return value: a new #GrssFeedEnclosure
+ * Return value: a new #GrssFeedEnclosure.
  */
 GrssFeedEnclosure* grss_feed_enclosure_new (gchar *url)
 {
@@ -84,11 +84,11 @@ GrssFeedEnclosure* grss_feed_enclosure_new (gchar *url)
 
 /**
  * grss_feed_enclosure_get_url:
- * @enclosure: a #GrssFeedEnclosure
+ * @enclosure: a #GrssFeedEnclosure.
  *
- * Retrieves the URL of the @enclosure
+ * Retrieves the URL of the @enclosure.
  *
- * Return value: the URL where the enclosure may be found
+ * Return value: the URL where the enclosure may be found.
  */
 const gchar* grss_feed_enclosure_get_url (GrssFeedEnclosure *enclosure)
 {
@@ -97,10 +97,10 @@ const gchar* grss_feed_enclosure_get_url (GrssFeedEnclosure *enclosure)
 
 /**
  * grss_feed_enclosure_set_format:
- * @enclosure: a #GrssFeedEnclosure
- * @type: type of content
+ * @enclosure: a #GrssFeedEnclosure.
+ * @type: type of content.
  *
- * To set the type of the external file
+ * To set the type of the external file.
  */
 void grss_feed_enclosure_set_format (GrssFeedEnclosure *enclosure, gchar *type)
 {
@@ -110,11 +110,11 @@ void grss_feed_enclosure_set_format (GrssFeedEnclosure *enclosure, gchar *type)
 
 /**
  * grss_feed_enclosure_get_format:
- * @enclosure: a #GrssFeedEnclosure
+ * @enclosure: a #GrssFeedEnclosure.
  *
- * Retrieves the format of the enclosed file
+ * Retrieves the format of the enclosed file.
  *
- * Return value: type of @enclosure
+ * Return value: type of @enclosure.
  */
 const gchar* grss_feed_enclosure_get_format (GrssFeedEnclosure *enclosure)
 {
@@ -123,10 +123,10 @@ const gchar* grss_feed_enclosure_get_format (GrssFeedEnclosure *enclosure)
 
 /**
  * grss_feed_enclosure_set_length:
- * @enclosure: a #GrssFeedEnclosure
- * @length: size of the enclosure, in bytes
+ * @enclosure: a #GrssFeedEnclosure.
+ * @length: size of the enclosure, in bytes.
  *
- * To set the size of the embedded @enclosure
+ * To set the size of the embedded @enclosure.
  */
 void grss_feed_enclosure_set_length (GrssFeedEnclosure *enclosure, gsize length)
 {
@@ -135,11 +135,11 @@ void grss_feed_enclosure_set_length (GrssFeedEnclosure *enclosure, gsize length)
 
 /**
  * grss_feed_enclosure_get_length:
- * @enclosure: a #GrssFeedEnclosure
+ * @enclosure: a #GrssFeedEnclosure.
  *
- * Retrieves the size of the embedded file
+ * Retrieves the size of the embedded file.
  *
- * Return value: size of the @enclosure, in bytes
+ * Return value: size of the @enclosure, in bytes.
  */
 gsize grss_feed_enclosure_get_length (GrssFeedEnclosure *enclosure)
 {
diff --git a/src/feed-item.c b/src/feed-item.c
index 9723183..baf837b 100644
--- a/src/feed-item.c
+++ b/src/feed-item.c
@@ -29,7 +29,8 @@
  * @short_description: a feed item
  *
  * #GrssFeedItem is an abstraction for an item, collects all information about a
- * single element found into a feed
+ * single element found into a feed. It mostly is a passive container for
+ * attributes.
  */
 
 /*
@@ -123,11 +124,11 @@ grss_feed_item_init (GrssFeedItem *node)
 
 /**
  * grss_feed_item_new:
- * @parent: the feed from which the new item belongs
+ * @parent: the feed from which the new item belongs.
  *
- * To allocate a new empty #GrssFeedItem
+ * To allocate a new empty #GrssFeedItem.
  *
- * Return value: a new #GrssFeedItem
+ * Return value: a new #GrssFeedItem.
  */
 GrssFeedItem*
 grss_feed_item_new (GrssFeedChannel *parent)
@@ -142,11 +143,11 @@ grss_feed_item_new (GrssFeedChannel *parent)
 
 /**
  * grss_feed_item_get_parent:
- * @item: a #GrssFeedItem
+ * @item: a #GrssFeedItem.
  *
- * Retrieves the feed from which the item belongs
+ * Retrieves the feed from which the item belongs.
  *
- * Return value: the parent feed, as set in grss_feed_item_new()
+ * Return value: the parent feed, as set in grss_feed_item_new().
  */
 GrssFeedChannel*
 grss_feed_item_get_parent (GrssFeedItem *item)
@@ -156,11 +157,11 @@ grss_feed_item_get_parent (GrssFeedItem *item)
 
 /**
  * grss_feed_item_set_id:
- * @item: a #GrssFeedItem
- * @id: the new ID to set
+ * @item: a #GrssFeedItem.
+ * @id: the new ID to set.
  *
  * To set the ID of the @item. This parameter has not a particular format: it
- * is just a string used to identify in unique way the item
+ * is just a string used to identify in unique way the item.
  */
 void
 grss_feed_item_set_id (GrssFeedItem *item, gchar *id)
@@ -181,14 +182,14 @@ grss_feed_item_set_id (GrssFeedItem *item, gchar *id)
 
 /**
  * grss_feed_item_get_id:
- * @item: #GrssFeedItem from which retrieve the ID
+ * @item: #GrssFeedItem from which retrieve the ID.
  *
  * Retrieves the ID assigned to the @item. If no ID was set with
  * grss_feed_item_set_id() this returns the same of grss_feed_item_get_source().
  * Pay attention to the fact this library do not check uniqueness of assigned
- * IDs
+ * IDs.
  *
- * Return value: ID of the item
+ * Return value: ID of the item.
  */
 const gchar*
 grss_feed_item_get_id (GrssFeedItem *item)
@@ -201,10 +202,10 @@ grss_feed_item_get_id (GrssFeedItem *item)
 
 /**
  * grss_feed_item_set_title:
- * @item: a #GrssFeedItem
- * @title: title of the item
+ * @item: a #GrssFeedItem.
+ * @title: title of the item.
  *
- * To set a title to the @item
+ * To set a title to the @item.
  */
 void
 grss_feed_item_set_title (GrssFeedItem *item, gchar *title)
@@ -215,11 +216,11 @@ grss_feed_item_set_title (GrssFeedItem *item, gchar *title)
 
 /**
  * grss_feed_item_get_title:
- * @item: a #GrssFeedItem
+ * @item: a #GrssFeedItem.
  *
- * Retrieves the title assigned to @item
+ * Retrieves the title assigned to @item.
  *
- * Return value: title of the element
+ * Return value: title of the element.
  */
 const gchar*
 grss_feed_item_get_title (GrssFeedItem *item)
@@ -229,10 +230,10 @@ grss_feed_item_get_title (GrssFeedItem *item)
 
 /**
  * grss_feed_item_set_description:
- * @item: a #GrssFeedItem
- * @description: content of the item
+ * @item: a #GrssFeedItem.
+ * @description: content of the item.
  *
- * To set the description of @item. Usually "description" means his content
+ * To set the description of @item. Usually "description" means his content.
  */
 void
 grss_feed_item_set_description (GrssFeedItem *item, gchar *description)
@@ -243,11 +244,11 @@ grss_feed_item_set_description (GrssFeedItem *item, gchar *description)
 
 /**
  * grss_feed_item_get_description:
- * @item: a #GrssFeedItem
+ * @item: a #GrssFeedItem.
  *
- * Retrieves the description of the @item
+ * Retrieves the description of the @item.
  *
- * Return value: description of @item
+ * Return value: description of @item.
  */
 const gchar*
 grss_feed_item_get_description (GrssFeedItem *item)
@@ -257,11 +258,11 @@ grss_feed_item_get_description (GrssFeedItem *item)
 
 /**
  * grss_feed_item_add_category:
- * @item: a #GrssFeedItem
- * @category: a new category to assign to the item
+ * @item: a #GrssFeedItem.
+ * @category: a new category to assign to the item.
  *
  * Adds a category to the @item. The complete list can be obtained with
- * grss_feed_item_get_categories()
+ * grss_feed_item_get_categories().
  */
 void
 grss_feed_item_add_category (GrssFeedItem *item, gchar *category)
@@ -278,12 +279,12 @@ grss_feed_item_add_category (GrssFeedItem *item, gchar *category)
 
 /**
  * grss_feed_item_get_categories:
- * @item: a #GrssFeedItem
+ * @item: a #GrssFeedItem.
  *
- * Retrieves list of categories assigned to the @item
+ * Retrieves list of categories assigned to the @item.
  *
  * Return value: list of strings, one for assigned category. Do not free or
- * modify this list
+ * modify this list.
  */
 const GList*
 grss_feed_item_get_categories (GrssFeedItem *item)
@@ -293,10 +294,10 @@ grss_feed_item_get_categories (GrssFeedItem *item)
 
 /**
  * grss_feed_item_set_source:
- * @item: a #GrssFeedItem
- * @source: URL of the item
+ * @item: a #GrssFeedItem.
+ * @source: URL of the item.
  *
- * To set the source of the @item
+ * To set the source of the @item.
  */
 void
 grss_feed_item_set_source (GrssFeedItem *item, gchar *source)
@@ -307,11 +308,11 @@ grss_feed_item_set_source (GrssFeedItem *item, gchar *source)
 
 /**
  * grss_feed_item_get_source:
- * @item: a #GrssFeedItem
+ * @item: a #GrssFeedItem.
  *
- * Retrieves the URL where the @item can be found
+ * Retrieves the URL where the @item can be found.
  *
- * Return value: URL of the item, or NULL
+ * Return value: URL of the item, or %NULL.
  */
 const gchar*
 grss_feed_item_get_source (GrssFeedItem *item)
@@ -321,12 +322,12 @@ grss_feed_item_get_source (GrssFeedItem *item)
 
 /**
  * grss_feed_item_set_real_source:
- * @item: a #GrssFeedItem
- * @realsource: URL of the real source for the item
- * @title: title of the real source
+ * @item: a #GrssFeedItem.
+ * @realsource: URL of the real source for the item.
+ * @title: title of the real source.
  *
  * To set an alternative real source for @item. This parameter is used by web
- * aggregators to explicit the origin of a content reproduced in them
+ * aggregators to explicit the origin of a content reproduced in them.
  */
 void
 grss_feed_item_set_real_source (GrssFeedItem *item, gchar *realsource, gchar *title)
@@ -339,11 +340,11 @@ grss_feed_item_set_real_source (GrssFeedItem *item, gchar *realsource, gchar *ti
 
 /**
  * grss_feed_item_get_real_source:
- * @item: a #GrssFeedItem
- * @realsource: will be assigned to the URL of the real source, or NULL
- * @title: will be assigned to the title of the real source, or NULL
+ * @item: a #GrssFeedItem.
+ * @realsource: will be assigned to the URL of the real source, or %NULL.
+ * @title: will be assigned to the title of the real source, or %NULL.
  *
- * Retrieves references to the real source of @item
+ * Retrieves references to the real source of @item.
  */
 void
 grss_feed_item_get_real_source (GrssFeedItem *item, const gchar **realsource, const gchar **title)
@@ -356,10 +357,10 @@ grss_feed_item_get_real_source (GrssFeedItem *item, const gchar **realsource, co
 
 /**
  * grss_feed_item_set_related:
- * @item: a #GrssFeedItem
- * @related: reference to a related post
+ * @item: a #GrssFeedItem.
+ * @related: reference to a related post.
  *
- * To set reference to a post related to @item
+ * To set reference to a post related to @item.
  */
 void
 grss_feed_item_set_related (GrssFeedItem *item, gchar *related)
@@ -370,11 +371,11 @@ grss_feed_item_set_related (GrssFeedItem *item, gchar *related)
 
 /**
  * grss_feed_item_get_related:
- * @item: a #GrssFeedItem
+ * @item: a #GrssFeedItem.
  *
- * Retrieves indication about posts related to @item
+ * Retrieves indication about posts related to @item.
  *
- * Return value: related posts, or NULL
+ * Return value: related posts, or %NULL.
  */
 const gchar*
 grss_feed_item_get_related (GrssFeedItem *item)
@@ -384,10 +385,10 @@ grss_feed_item_get_related (GrssFeedItem *item)
 
 /**
  * grss_feed_item_set_copyright:
- * @item: a #GrssFeedItem
- * @copyright: copyright declaration for the item
+ * @item: a #GrssFeedItem.
+ * @copyright: copyright declaration for the item.
  *
- * To set a copyright reference to @item
+ * To set a copyright reference to @item.
  */
 void
 grss_feed_item_set_copyright (GrssFeedItem *item, gchar *copyright)
@@ -398,11 +399,11 @@ grss_feed_item_set_copyright (GrssFeedItem *item, gchar *copyright)
 
 /**
  * grss_feed_item_get_copyright:
- * @item: a #GrssFeedItem
+ * @item: a #GrssFeedItem.
  *
- * Retrieves copyright reference for the @item
+ * Retrieves copyright reference for the @item.
  *
- * Return value: copyright mark, or NULL
+ * Return value: copyright mark, or %NULL.
  */
 const gchar*
 grss_feed_item_get_copyright (GrssFeedItem *item)
@@ -412,10 +413,10 @@ grss_feed_item_get_copyright (GrssFeedItem *item)
 
 /**
  * grss_feed_item_set_author:
- * @item: a #GrssFeedItem
- * @author: name of the author
+ * @item: a #GrssFeedItem.
+ * @author: name of the author.
  *
- * To assign an author to the @item
+ * To assign an author to the @item.
  */
 void
 grss_feed_item_set_author (GrssFeedItem *item, gchar *author)
@@ -426,11 +427,11 @@ grss_feed_item_set_author (GrssFeedItem *item, gchar *author)
 
 /**
  * grss_feed_item_get_author:
- * @item: a #GrssFeedItem
+ * @item: a #GrssFeedItem.
  *
- * Retrieves the author of @item
+ * Retrieves the author of @item.
  *
- * Return value: author of the item, or NULL
+ * Return value: author of the item, or %NULL.
  */
 const gchar*
 grss_feed_item_get_author (GrssFeedItem *item)
@@ -440,10 +441,10 @@ grss_feed_item_get_author (GrssFeedItem *item)
 
 /**
  * grss_feed_item_add_contributor:
- * @item: a #GrssFeedItem
- * @contributor: name of the contributor for the item
+ * @item: a #GrssFeedItem.
+ * @contributor: name of the contributor for the item.
  *
- * To add a contributor to the @item
+ * To add a contributor to the @item.
  */
 void
 grss_feed_item_add_contributor (GrssFeedItem *item, gchar *contributor)
@@ -460,11 +461,11 @@ grss_feed_item_add_contributor (GrssFeedItem *item, gchar *contributor)
 
 /**
  * grss_feed_item_get_contributors:
- * @item: a #GrssFeedItem
+ * @item: a #GrssFeedItem.
  *
- * Retrieves contributors for @item
+ * Retrieves contributors for @item.
  *
- * Return value: list of contributors to the item
+ * Return value: list of contributors to the item.
  */
 const GList*
 grss_feed_item_get_contributors (GrssFeedItem *item)
@@ -474,10 +475,10 @@ grss_feed_item_get_contributors (GrssFeedItem *item)
 
 /**
  * grss_feed_item_set_comments_url:
- * @item: a #GrssFeedItem
- * @url: URL where to retrieve comments to the item
+ * @item: a #GrssFeedItem.
+ * @url: URL where to retrieve comments to the item.
  *
- * To assign the URL where to fetch comments for the item
+ * To assign the URL where to fetch comments for the item.
  */
 void
 grss_feed_item_set_comments_url (GrssFeedItem *item, gchar *url)
@@ -488,11 +489,11 @@ grss_feed_item_set_comments_url (GrssFeedItem *item, gchar *url)
 
 /**
  * grss_feed_item_get_comments_url:
- * @item: a #GrssFeedItem
+ * @item: a #GrssFeedItem.
  *
- * Retrieves the URL where to catch comments to the @item
+ * Retrieves the URL where to catch comments to the @item.
  *
- * Return value: URL to parse to read comments for @item, or NULL
+ * Return value: URL to parse to read comments for @item, or %NULL.
  */
 const gchar*
 grss_feed_item_get_comments_url (GrssFeedItem *item)
@@ -502,14 +503,14 @@ grss_feed_item_get_comments_url (GrssFeedItem *item)
 
 /**
  * grss_feed_item_set_geo_point:
- * @item: a #GrssFeedItem
- * @latitude: latitude of the point, or -1 to leave the previous one
- * @longitude: longitude of the point, or -1 to leave the previous one
+ * @item: a #GrssFeedItem.
+ * @latitude: latitude of the point, or -1 to leave the previous one.
+ * @longitude: longitude of the point, or -1 to leave the previous one.
  *
  * To assign geographic context to the @item.
  * Passing -1 as @latitude or @longitude, the relative value is untouched in
  * the object. This is to easy assignment of coordinates in more than a
- * single step. If both are -1, nothing happens
+ * single step. If both are -1, nothing happens.
  */
 void
 grss_feed_item_set_geo_point (GrssFeedItem *item, double latitude, double longitude)
@@ -528,15 +529,15 @@ grss_feed_item_set_geo_point (GrssFeedItem *item, double latitude, double longit
 
 /**
  * grss_feed_item_get_geo_point:
- * @item: a #GrssFeedItem
- * @latitude: will be assigned to the latitude of the point, or NULL
- * @longitude: will be assigned to the longitude of the point, or NULL
+ * @item: a #GrssFeedItem.
+ * @latitude: will be assigned to the latitude of the point, or %NULL.
+ * @longitude: will be assigned to the longitude of the point, or %NULL.
  *
- * Retrieves the geo reference of the @item
+ * Retrieves the geo reference of the @item.
  *
  * Return value: %TRUE if @item has geographic coordinates assigned and
  * @latitude and @longitude have been set, %FALSE if @item has not geo
- * reference
+ * reference.
  */
 gboolean
 grss_feed_item_get_geo_point (GrssFeedItem *item, double *latitude, double *longitude)
@@ -551,10 +552,10 @@ grss_feed_item_get_geo_point (GrssFeedItem *item, double *latitude, double *long
 
 /**
  * grss_feed_item_set_publish_time:
- * @item: a #GrssFeedItem
- * @publish: publishing timestamp of the item
+ * @item: a #GrssFeedItem.
+ * @publish: publishing timestamp of the item.
  *
- * To set the publish time of the item
+ * To set the publish time of the item.
  */
 void
 grss_feed_item_set_publish_time (GrssFeedItem *item, time_t publish)
@@ -564,13 +565,13 @@ grss_feed_item_set_publish_time (GrssFeedItem *item, time_t publish)
 
 /**
  * grss_feed_item_get_publish_time:
- * @item: a #GrssFeedItem
+ * @item: a #GrssFeedItem.
  *
  * Retrieves the publish time of the item. By default this value is the
- * current timestamp assigned when creating the #GrssFeedItem, and may be changed
- * with grss_feed_item_set_publish_time()
+ * current timestamp assigned when creating the #GrssFeedItem, and may be
+ * changed with grss_feed_item_set_publish_time().
  *
- * Return value: publish time of @item
+ * Return value: publish time of @item.
  */
 time_t
 grss_feed_item_get_publish_time (GrssFeedItem *item)
@@ -580,12 +581,12 @@ grss_feed_item_get_publish_time (GrssFeedItem *item)
 
 /**
  * grss_feed_item_add_enclosure:
- * @item: a #GrssFeedItem
- * @enclosure: a #GrssFeedEnclosure to add to the item
+ * @item: a #GrssFeedItem.
+ * @enclosure: a #GrssFeedEnclosure to add to the item.
  *
  * Adds an enclosure to the @item. That external elements may be references
  * to images, videos, or other contents (usually multimedial) embedded in the
- * element
+ * element.
  */
 void
 grss_feed_item_add_enclosure (GrssFeedItem *item, GrssFeedEnclosure *enclosure)
@@ -598,12 +599,12 @@ grss_feed_item_add_enclosure (GrssFeedItem *item, GrssFeedEnclosure *enclosure)
 
 /**
  * grss_feed_item_get_enclosures:
- * @item: a #GrssFeedItem
+ * @item: a #GrssFeedItem.
  *
- * Retrieves the list of enclosures added with grss_feed_item_add_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
- * internal list, do not free or modify it
+ * internal list, do not free or modify it.
  */
 const GList*
 grss_feed_item_get_enclosures (GrssFeedItem *item)
diff --git a/src/feed-parser.c b/src/feed-parser.c
index b64d88c..a30bfe8 100644
--- a/src/feed-parser.c
+++ b/src/feed-parser.c
@@ -115,9 +115,9 @@ feed_parsers_get_list (GrssFeedParser *parser)
 /**
  * grss_feed_parser_new:
  *
- * Allocates a new #GrssFeedParser
+ * Allocates a new #GrssFeedParser.
  *
- * Return value: a new #GrssFeedParser
+ * Return value: a new #GrssFeedParser.
  */
 GrssFeedParser*
 grss_feed_parser_new ()
@@ -150,17 +150,17 @@ retrieve_feed_handler (GrssFeedParser *parser, xmlDocPtr doc, xmlNodePtr cur)
 
 /**
  * grss_feed_parser_parse:
- * @parser: a #GrssFeedParser
- * @feed: a #GrssFeedChannel to be parsed
+ * @parser: a #GrssFeedParser.
+ * @feed: a #GrssFeedChannel to be parsed.
  * @doc: XML document extracted from the contents of the feed, which must
- * already been fetched
- * @error: location for eventual errors
+ *       already been fetched.
+ * @error: location for eventual errors.
  *
  * Parses the given XML @doc, belonging to the given @feed, to obtain a list
- * of #GrssFeedItem
+ * 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
+ * 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 58e89fe..26333f6 100644
--- a/src/feeds-group.c
+++ b/src/feeds-group.c
@@ -32,8 +32,8 @@
  * SECTION: feeds-group
  * @short_description: import and export group of channels
  *
- * #GrssFeedsGroup is an utility to import and export list of #GrssFeedChannels in
- * different formats, such as OPML and XOXO.
+ * #GrssFeedsGroup is an utility to read and write lists of #GrssFeedChannels
+ * in different formats, such as OPML and XOXO.
  */
 
 #define FEEDS_GROUP_ERROR		grss_feeds_group_error_quark()
@@ -101,9 +101,9 @@ feeds_groups_get_list (GrssFeedsGroup *group)
 /**
  * grss_feeds_group_new:
  *
- * Allocates a new #GrssFeedsGroup
+ * Allocates a new #GrssFeedsGroup.
  *
- * Return value: a new #GrssFeedsGroup
+ * Return value: a new #GrssFeedsGroup.
  */
 GrssFeedsGroup*
 grss_feeds_group_new ()
@@ -137,12 +137,12 @@ retrieve_group_handler (GrssFeedsGroup *group, xmlDocPtr doc, xmlNodePtr cur)
 
 /**
  * grss_feeds_group_get_formats:
- * @group: a #GrssFeedsGroupClass
+ * @group: a #GrssFeedsGroupClass.
  *
- * Returns the list of supported file formats
+ * 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: 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)
@@ -165,14 +165,14 @@ grss_feeds_group_get_formats (GrssFeedsGroup *group)
 
 /**
  * grss_feeds_group_parse_file:
- * @group: a #GrssFeedsGroup
- * @path: path of the file to parse
- * @error: location for eventual errors
+ * @group: a #GrssFeedsGroup.
+ * @path: path of the file to parse.
+ * @error: location for eventual errors.
  *
- * Parses the given file to obtain list of listed feeds
+ * 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
+ * @error is set.
  */
 GList*
 grss_feeds_group_parse_file (GrssFeedsGroup *group, const gchar *path, GError **error)
@@ -219,13 +219,18 @@ grss_feeds_group_parse_file (GrssFeedsGroup *group, const gchar *path, GError **
 
 /**
  * grss_feeds_group_export_file:
- * @group:
- * @channels:
- * @format:
- * @uri:
- * @error:
+ * @group: a #GrssFeedsGroup.
+ * @channels: 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.
+ * @error: location for eventual errors.
  *
- * Return value: %FALSE
+ * Creates a new file with the list of @channels rappresented in the required
+ * @format. It a file already exists at the @uri location, it is overwritten.
+ * 
+ * Return value: %TRUE if the file is created correctly, or %FALSE if an error
+ * occours and @error is set.
  */
 gboolean
 grss_feeds_group_export_file (GrssFeedsGroup *group, GList *channels, const gchar *format, const gchar *uri, GError **error)
diff --git a/src/feeds-pool.c b/src/feeds-pool.c
index 968b56c..14ce06e 100644
--- a/src/feeds-pool.c
+++ b/src/feeds-pool.c
@@ -32,7 +32,7 @@
  * The #GrssFeedsPool permits to automatically "listen" for more feeds: it
  * provides to fetch them on regular intervals (as defined by
  * grss_feed_channel_get_update_interval() for each channel), parse them with
- * #GrssFeedParser, and emits signals when feeds are ready
+ * #GrssFeedParser, and emits signals when feeds are ready.
  */
 
 struct _GrssFeedsPoolPrivate {
@@ -116,11 +116,11 @@ grss_feeds_pool_class_init (GrssFeedsPoolClass *klass)
 
 	/**
 	 * GrssFeedsPool::feed-fetching:
-	 * @pool: the #GrssFeedsPool emitting the signal
-	 * @feed: the #GrssFeedChannel which is going to be fetched
+	 * @pool: the #GrssFeedsPool emitting the signal.
+	 * @feed: the #GrssFeedChannel which is going to be fetched.
 	 *
 	 * Emitted when the @pool starts fetching a new #GrssFeedChannel. To be
-	 * used to know the internal status of the component
+	 * used to know the internal status of the component.
 	 */
 	signals [FEED_FETCHING] = g_signal_new ("feed-fetching", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST, 0,
 	                                        NULL, NULL, g_cclosure_marshal_VOID__OBJECT,
@@ -128,15 +128,15 @@ grss_feeds_pool_class_init (GrssFeedsPoolClass *klass)
 
 	/**
 	 * GrssFeedsPool::feed-ready:
-	 * @pool: the #GrssFeedsPool emitting the signal
-	 * @feed: the #GrssFeedChannel which has been fetched and parsed
-	 * @items: list of #GrssFeedItem obtained parsing the feed
+	 * @pool: the #GrssFeedsPool emitting the signal.
+	 * @feed: the #GrssFeedChannel which has been fetched and parsed.
+	 * @items: list of #GrssFeedItem obtained parsing the feed.
 	 *
 	 * Emitted when a #GrssFeedChannel assigned to the @pool has been fetched
 	 * and parsed. All parsed items are exposed in the array, with no
 	 * regards about previously existing elements. @items may be NULL, if
 	 * an error occourred while fetching and/or parsing. List of @items
-	 * is freed, and his elements are unref'd, when signal ends
+	 * is freed, and his elements are unref'd, when signal ends.
 	 */
 	signals [FEED_READY] = g_signal_new ("feed-ready", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST, 0,
 	                                     NULL, NULL, feed_marshal_VOID__OBJECT_POINTER,
@@ -155,9 +155,9 @@ grss_feeds_pool_init (GrssFeedsPool *node)
 /**
  * grss_feeds_pool_new:
  *
- * Allocates a new #GrssFeedsPool
+ * Allocates a new #GrssFeedsPool.
  *
- * Return value: a new #GrssFeedsPool
+ * Return value: a new #GrssFeedsPool.
  */
 GrssFeedsPool*
 grss_feeds_pool_new ()
@@ -190,15 +190,15 @@ create_listened (GrssFeedsPool *pool, GList *feeds)
 
 /**
  * grss_feeds_pool_listen:
- * @pool: a #GrssFeedsPool
- * @feeds: a list of #GrssFeedChannel
+ * @pool: a #GrssFeedsPool.
+ * @feeds: 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()
  * must be call to run the auto-fetching (always, also if previous state was
  * "running").
  * The list in @feeds can be freed after calling this; linked #GrssFeedChannel
- * are g_object_ref'd here
+ * are g_object_ref'd here.
  */
 void
 grss_feeds_pool_listen (GrssFeedsPool *pool, GList *feeds)
@@ -214,15 +214,15 @@ grss_feeds_pool_listen (GrssFeedsPool *pool, GList *feeds)
 
 /**
  * grss_feeds_pool_get_listened:
- * @pool: a #GrssFeedsPool
+ * @pool: a #GrssFeedsPool.
  *
  * Returns the list of feeds currently managed by the @pool. Please consider
  * this function has to build the list that returns, and of course this is a
  * time and resources consuming task: if you only need to know how many feeds
- * are currently handled, check grss_feeds_pool_get_listened_num()
+ * 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
+ * no longer in use. Do not modify elements found in this list.
  */
 GList*
 grss_feeds_pool_get_listened (GrssFeedsPool *pool)
@@ -244,9 +244,9 @@ grss_feeds_pool_get_listened (GrssFeedsPool *pool)
  *
  * Returns number of feeds under the @pool control, as provided by
  * grss_feeds_pool_listen(). To get the complete list of those feeds, check
- * grss_feeds_pool_get_listened()
+ * grss_feeds_pool_get_listened().
  *
- * Return value: number of feeds currently managed by the #GrssFeedsPool
+ * Return value: number of feeds currently managed by the #GrssFeedsPool.
  */
 int
 grss_feeds_pool_get_listened_num (GrssFeedsPool *pool)
@@ -340,11 +340,11 @@ run_scheduler (GrssFeedsPool *pool)
 
 /**
  * grss_feeds_pool_switch:
- * @pool: a #GrssFeedsPool
- * @run: %TRUE to run the pool, %FALSE to pause it
+ * @pool: a #GrssFeedsPool.
+ * @run: %TRUE to run the pool, %FALSE to pause it.
  *
  * Permits to pause or resume the @pool fetching feeds. If @run is %TRUE, the
- * @pool starts immediately
+ * @pool starts immediately.
  */
 void
 grss_feeds_pool_switch (GrssFeedsPool *pool, gboolean run)
@@ -364,11 +364,11 @@ grss_feeds_pool_switch (GrssFeedsPool *pool, gboolean run)
 
 /**
  * grss_feeds_pool_get_session:
- * @pool: a #GrssFeedsPool
+ * @pool: a #GrssFeedsPool.
  *
- * To access the internal #SoupSession used by the @pool to fetch items
+ * To access the internal #SoupSession used by the @pool to fetch items.
  *
- * Return value: istance of #SoupSession. Do not free it
+ * Return value: istance 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 0720729..f487257 100644
--- a/src/feeds-publisher.c
+++ b/src/feeds-publisher.c
@@ -33,11 +33,11 @@
  * SECTION: feeds-publisher
  * @short_description: feed writer and PubSubHubBub publisher
  *
- * #GrssFeedsPublisher may be used to expose contents for any given #GrssFeedChannel,
- * both writing a file to be dispatched by the local webserver or providing
- * himself to distribute it, and implements a server able to receive
- * subscriptions by PubSubHubbub clients and deliver them new contents in
- * real-time.
+ * #GrssFeedsPublisher may be used to expose contents for any given
+ * #GrssFeedChannel, both writing a file to be dispatched by the local webserver
+ * or providing himself to distribute it, and implements a server able to
+ * receive subscriptions by PubSubHubbub clients and deliver them new contents
+ * in real-time.
  */
 
 static void	subscribe_verify_cb	(SoupSession *session, SoupMessage *msg, gpointer user_data);
@@ -165,11 +165,11 @@ grss_feeds_publisher_class_init (GrssFeedsPublisherClass *klass)
 
 	/**
 	 * GrssFeedsPublisher::new_subscription:
-	 * @pub: the #GrssFeedsPublisher emitting the signal
-	 * @topic: #GrssFeedChannel for which subscription has been added
-	 * @callback: callback required for new subscriber
+	 * @pub: the #GrssFeedsPublisher emitting the signal.
+	 * @topic: #GrssFeedChannel for which subscription has been added.
+	 * @callback: callback required for new subscriber.
 	 *
-	 * Emitted when a new remote client subscribes to this publisher
+	 * Emitted when a new remote client subscribes to this publisher.
 	 */
 	signals [SUBSCRIPTION_ADDED] = g_signal_new ("new-subscription", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST, 0,
 	                                             NULL, NULL, feed_marshal_VOID__OBJECT_STRING,
@@ -177,11 +177,11 @@ grss_feeds_publisher_class_init (GrssFeedsPublisherClass *klass)
 
 	/**
 	 * GrssFeedsPublisher::new_subscription:
-	 * @pub: the #GrssFeedsPublisher emitting the signal
-	 * @topic: #GrssFeedChannel for which subscription has been removed
-	 * @callback: callback revoked by the subscriber
+	 * @pub: the #GrssFeedsPublisher emitting the signal.
+	 * @topic: #GrssFeedChannel for which subscription has been removed.
+	 * @callback: callback revoked by the subscriber.
 	 *
-	 * Emitted when a new remote client unsubscribes to this publisher
+	 * Emitted when a new remote client unsubscribes to this publisher.
 	 */
 	signals [SUBSCRIPTION_DELETED] = g_signal_new ("delete-subscription", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST, 0,
 	                                               NULL, NULL, feed_marshal_VOID__OBJECT_STRING,
@@ -200,9 +200,9 @@ grss_feeds_publisher_init (GrssFeedsPublisher *node)
 /**
  * grss_feeds_publisher_new:
  *
- * Allocates a new #GrssFeedsPublisher
+ * Allocates a new #GrssFeedsPublisher.
  *
- * Return value: a new #GrssFeedsPublisher
+ * Return value: a new #GrssFeedsPublisher.
  */
 GrssFeedsPublisher*
 grss_feeds_publisher_new ()
@@ -479,17 +479,18 @@ feed_required_by_web_cb (SoupServer *server, SoupMessage *msg, const char *path,
 
 /**
  * grss_feeds_publisher_publish:
- * @pub: a #GrssFeedsPublisher
- * @channel: the #GrssFeedChannel to dump in the file
- * @items: 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
+ * @pub: a #GrssFeedsPublisher.
+ * @channel: the #GrssFeedChannel to dump in the file.
+ * @items: 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.
  *
  * If the local web server has been executed (with
- * grss_feeds_publisher_hub_switch()) this function exposes the given @channel as
- * an Atom formatted file avalable to http://[LOCAL_IP:DEFINED_PORT]/@id
+ * grss_feeds_publisher_hub_switch()) this function exposes the given @channel
+ * as an Atom formatted file avalable to http://[LOCAL_IP:DEFINED_PORT]/@id .
  * 
- * Return value: %TRUE if the file is successfully written, %FALSE otherwise
+ * Return value: %TRUE if the file is successfully written, %FALSE otherwise.
  */
 gboolean
 grss_feeds_publisher_publish (GrssFeedsPublisher *pub, GrssFeedChannel *channel, GList *items, const gchar *id, GError **error)
@@ -521,18 +522,19 @@ grss_feeds_publisher_publish (GrssFeedsPublisher *pub, GrssFeedChannel *channel,
 
 /**
  * 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
- * @uri: URI of the file to write
- * @error: if an error occourred, %FALSE is returned and this is filled with the message
+ * @pub: a #GrssFeedsPublisher.
+ * @channel: the #GrssFeedChannel to dump in the file.
+ * @items: 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.
  *
  * Dump the given @channel in an Atom formatted file in @path. If the local
  * PubSubHubbub hub has been activated (with grss_feeds_publisher_hub_switch())
  * notifies remote subscribers about the new items which has been added since
- * previous invocation of this function for the same #GrssFeedChannel
+ * previous invocation of this function for the same #GrssFeedChannel.
  * 
- * Return value: %TRUE if the file is successfully written, %FALSE otherwise
+ * Return value: %TRUE if the file is successfully written, %FALSE otherwise.
  */
 gboolean
 grss_feeds_publisher_publish_file (GrssFeedsPublisher *pub, GrssFeedChannel *channel, GList *items, const gchar *uri, GError **error)
@@ -873,12 +875,12 @@ create_and_run_server (GrssFeedsPublisher *pub)
 
 /**
  * grss_feeds_publisher_hub_set_port:
- * @pub: a #GrssFeedsPublisher
- * @port: new listening port for the server
+ * @pub: a #GrssFeedsPublisher.
+ * @port: new listening port for the server.
  *
  * To customize the port opened by the local server to deliver feeds and
  * catch incoming subscriptions. By default this is 80. Changing the port
- * while the hub is running imply restart the local server
+ * while the hub is running imply restart the local server.
  */
 void
 grss_feeds_publisher_hub_set_port (GrssFeedsPublisher *pub, int port)
@@ -895,15 +897,15 @@ grss_feeds_publisher_hub_set_port (GrssFeedsPublisher *pub, int port)
 
 /**
  * grss_feeds_publisher_hub_set_topics:
- * @pub: a #GrssFeedsPublisher
- * @topics: a list of #GrssFeedChannels
+ * @pub: a #GrssFeedsPublisher.
+ * @topics: 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
  * grss_feed_channel_get_source(), are accepted as "hub.topic" parameter in
  * PubSubHubbub registration requests from remote subscribers.
  * Pay attention to the fact subscriptions requests for different topic are
- * now rejected
+ * now rejected.
  */
 void
 grss_feeds_publisher_hub_set_topics (GrssFeedsPublisher *pub, GList *topics)
@@ -969,10 +971,10 @@ remove_refresh_handler (GrssFeedsPublisher *pub)
 
 /**
  * grss_feeds_publisher_hub_switch:
- * @pub: a #GrssFeedsPublisher
- * @run: %TRUE to run the local server, %FALSE to stop it
+ * @pub: a #GrssFeedsPublisher.
+ * @run: %TRUE to run the local server, %FALSE to stop it.
  *
- * Permits to start and stop the webserver implemented by this object
+ * Permits to start and stop the webserver implemented by this object.
  */
 void
 grss_feeds_publisher_hub_switch (GrssFeedsPublisher *pub, gboolean run)
diff --git a/src/feeds-store.c b/src/feeds-store.c
index 136198f..846bf44 100644
--- a/src/feeds-store.c
+++ b/src/feeds-store.c
@@ -55,12 +55,12 @@ grss_feeds_store_init (GrssFeedsStore *node)
 
 /**
  * grss_feeds_store_get_channels:
- * @store: a #GrssFeedsStore
+ * @store: a #GrssFeedsStore.
  *
- * To retrieve list of feeds permanently saved into the store
+ * 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
+ * free it.
  */
 GList*
 grss_feeds_store_get_channels (GrssFeedsStore *store)
@@ -70,14 +70,14 @@ grss_feeds_store_get_channels (GrssFeedsStore *store)
 
 /**
  * grss_feeds_store_get_items_by_channel:
- * @store: a #GrssFeedsStore
- * @channel: parent feed containing required items
+ * @store: a #GrssFeedsStore.
+ * @channel: parent feed containing required items.
  *
  * To retrieve list of items saved into the store, assigned to the given
- * @channel
+ * @channel.
  *
  * Return value: list of #GrssFeedItem found in the @store. Do not modify or free
- * it
+ * it.
  */
 GList*
 grss_feeds_store_get_items_by_channel (GrssFeedsStore *store, GrssFeedChannel *channel)
@@ -87,13 +87,13 @@ grss_feeds_store_get_items_by_channel (GrssFeedsStore *store, GrssFeedChannel *c
 
 /**
  * grss_feeds_store_has_item:
- * @store: a #GrssFeedsStore
- * @channel: parent feed containing required item
- * @id: unique ID to look for
+ * @store: a #GrssFeedsStore.
+ * @channel: parent feed containing required item.
+ * @id: unique ID to look for.
  *
- * To retrieve an item into a feed, given his unique ID
+ * To retrieve an item into a feed, given his unique ID.
  *
- * Return value: %TRUE if the specified item exists, %FALSE otherwise
+ * Return value: %TRUE if the specified item exists, %FALSE otherwise.
  */
 gboolean
 grss_feeds_store_has_item (GrssFeedsStore *store, GrssFeedChannel *channel, const gchar *id)
@@ -103,12 +103,12 @@ grss_feeds_store_has_item (GrssFeedsStore *store, GrssFeedChannel *channel, cons
 
 /**
  * grss_feeds_store_add_item_in_channel:
- * @store: a #GrssFeedsStore
- * @channel: parent feed for the new item
- * @item: new item to permanently save
+ * @store: a #GrssFeedsStore.
+ * @channel: parent feed for the new item.
+ * @item: new item to permanently save.
  *
  * To save a new #GrssFeedItem into the @store. It performs a check to grant
- * @item is not already saved
+ * @item is not already saved.
  */
 void
 grss_feeds_store_add_item_in_channel (GrssFeedsStore *store, GrssFeedChannel *channel, GrssFeedItem *item)
@@ -134,12 +134,12 @@ feed_fetched (GrssFeedsPool *pool, GrssFeedChannel *feed, GList *items, gpointer
 
 /**
  * grss_feeds_store_switch:
- * @store: a #GrssFeedsStore
- * @run: %TRUE to run the @store, %FALSE to stop
+ * @store: a #GrssFeedsStore.
+ * @run: %TRUE to run the @store, %FALSE to stop.
  *
  * This is to permit the @store to auto-update itself: it creates an internal
  * #GrssFeedsPool and listens for his signals, so to implement the whole loop
- * fetch-parse-save trasparently
+ * fetch-parse-save trasparently.
  */
 void
 grss_feeds_store_switch (GrssFeedsStore *store, gboolean run)
diff --git a/src/feeds-subscriber.c b/src/feeds-subscriber.c
index a336a86..eed970e 100644
--- a/src/feeds-subscriber.c
+++ b/src/feeds-subscriber.c
@@ -41,6 +41,9 @@
  * engage a subscription for each #GrssFeedChannel passed with
  * grss_feeds_subscriber_listen(), and waits for direct notifications by the
  * remote server.
+ * 
+ * Pay attention to the fact this object doesn't provides any NAT traversing
+ * method to receive notification while behind a NAT.
  */
 
 /*
@@ -147,13 +150,13 @@ grss_feeds_subscriber_class_init (GrssFeedsSubscriberClass *klass)
 
 	/**
 	 * GrssFeedsSubscriber::notification-received:
-	 * @pool: the #GrssFeedsSubscriber emitting the signal
-	 * @feed: the #GrssFeedChannel which has been updated
-	 * @item: the #GrssFeedItem received
+	 * @pool: the #GrssFeedsSubscriber emitting the signal.
+	 * @feed: the #GrssFeedChannel which has been updated.
+	 * @item: the #GrssFeedItem received.
 	 *
 	 * Emitted when a notification has been received and parsed. The
 	 * @item is cached and unref'd when the #GrssFeedsSubscriber is
-	 * destroyed or a new set of feeds is provided
+	 * destroyed or a new set of feeds is provided.
 	 */
 	signals [NOTIFICATION_RECEIVED] = g_signal_new ("notification-received", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST, 0,
 	                                                NULL, NULL, feed_marshal_VOID__OBJECT_OBJECT,
@@ -184,9 +187,9 @@ grss_feeds_subscriber_init (GrssFeedsSubscriber *node)
 /**
  * grss_feeds_subscriber_new:
  *
- * Allocates a new #GrssFeedsSubscriber
+ * Allocates a new #GrssFeedsSubscriber.
  *
- * Return value: a new #GrssFeedsSubscriber
+ * Return value: a new #GrssFeedsSubscriber.
  */
 GrssFeedsSubscriber*
 grss_feeds_subscriber_new ()
@@ -247,17 +250,17 @@ create_listened (GrssFeedsSubscriber *sub, GList *feeds)
 
 /**
  * grss_feeds_subscriber_listen:
- * @sub: a #GrssFeedsSubscriber
- * @feeds: a list of #GrssFeedChannel
+ * @sub: a #GrssFeedsSubscriber.
+ * @feeds: 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()
  * must be call to run the subscription.
  * The list in @feeds can be freed after calling this; linked #GrssFeedChannel
- * are g_object_ref'd here
+ * are g_object_ref'd here.
  *
  * Return value: %TRUE if all #GrssFeedChannels involved in @feeds are valid
- * and can be listened with one of the implemented procotols, %FALSE otherwise
+ * and can be listened with one of the implemented procotols, %FALSE otherwise.
  */
 gboolean
 grss_feeds_subscriber_listen (GrssFeedsSubscriber *sub, GList *feeds)
@@ -268,12 +271,12 @@ grss_feeds_subscriber_listen (GrssFeedsSubscriber *sub, GList *feeds)
 
 /**
  * grss_feeds_subscriber_get_listened:
- * @sub: a #GrssFeedsSubscriber
+ * @sub: a #GrssFeedsSubscriber.
  *
- * Returns the list of feeds currently managed by @sub
+ * 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
+ * no longer in use. Do not modify elements found in this list.
  */
 GList*
 grss_feeds_subscriber_get_listened (GrssFeedsSubscriber *sub)
@@ -568,14 +571,14 @@ stop_server (GrssFeedsSubscriber *sub)
 
 /**
  * grss_feeds_subscriber_set_port:
- * @sub: a #GrssFeedsSubscriber
- * @port: new listening port for the server
+ * @sub: a #GrssFeedsSubscriber.
+ * @port: new listening port for the server.
  *
  * To customize the port opened by the local server to catch incoming
  * publishers' events. By default this is 8444. Changing the port while the
  * subscriber is running imply restart the local server.
  * Pay attention to the fact many publishers' implementations accept only
- * certain ports
+ * certain ports.
  */
 void
 grss_feeds_subscriber_set_port (GrssFeedsSubscriber *sub, int port)
@@ -592,10 +595,10 @@ grss_feeds_subscriber_set_port (GrssFeedsSubscriber *sub, int port)
 
 /**
  * grss_feeds_subscriber_switch:
- * @sub: a #GrssFeedsSubscriber
- * @run: %TRUE to run the subscriber, %FALSE to pause it
+ * @sub: a #GrssFeedsSubscriber.
+ * @run: %TRUE to run the subscriber, %FALSE to pause it.
  *
- * Permits to pause or resume @sub listening for events
+ * Permits to pause or resume @sub listening for events.
  */
 void
 grss_feeds_subscriber_switch (GrssFeedsSubscriber *sub, gboolean run)
@@ -612,14 +615,14 @@ grss_feeds_subscriber_switch (GrssFeedsSubscriber *sub, gboolean run)
 
 /**
  * grss_feeds_subscriber_get_address:
- * @sub: a #GrssFeedsSubscriber
+ * @sub: a #GrssFeedsSubscriber.
  *
  * This function returns the Internet address where @sub is listening for
  * external events. It is often required by #GrssFeedsSubscriberHandlers while
- * subscribing contents to specify the local endpoint for communications
+ * subscribing contents to specify the local endpoint for communications.
  *
  * Return value: the #GInetAddress used by @sub, or %NULL if the
- * #GrssFeedsSubscriber is switched off
+ * #GrssFeedsSubscriber is switched off.
  */
 GInetAddress*
 grss_feeds_subscriber_get_address (GrssFeedsSubscriber *sub)
@@ -629,13 +632,13 @@ grss_feeds_subscriber_get_address (GrssFeedsSubscriber *sub)
 
 /**
  * grss_feeds_subscriber_get_port:
- * @sub: a #GrssFeedsSubscriber
+ * @sub: a #GrssFeedsSubscriber.
  *
  * This function returns the Internet port where @sub is listening for
  * external events. It is often required by #GrssFeedsSubscriberHandlers while
- * subscribing contents to specify the local endpoint for communications
+ * subscribing contents to specify the local endpoint for communications.
  * 
- * Return value: the port of the socket locally opened by @sub
+ * Return value: the port of the socket locally opened by @sub.
  */
 int
 grss_feeds_subscriber_get_port (GrssFeedsSubscriber *sub)
@@ -645,12 +648,12 @@ grss_feeds_subscriber_get_port (GrssFeedsSubscriber *sub)
 
 /**
  * grss_feeds_subscriber_get_session:
- * @sub: a #GrssFeedsSubscriber
+ * @sub: a #GrssFeedsSubscriber.
  *
  * To obtain the internal #SoupSession of a #GrssFeedsSubscriber, so to re-use
- * it in #GrssFeedsSubscriberHandlers or similar tasks
+ * it in #GrssFeedsSubscriberHandlers or similar tasks.
  * 
- * Return value: the #SoupSession used by the provided #GrssFeedsSubscriber
+ * Return value: 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]