[libgdata] core: Expand the cancellation docs on gdata_service_query()

[Philip Withnall <pwithnall src gnome org>]

commit 877c9b0b3ca169d0edd7280b256b0af658a6803a
Author: Philip Withnall <philip tecnocode co uk>
Date:   Thu Dec 16 14:06:09 2010 +0000

    core: Expand the cancellation docs on gdata_service_query()

 docs/reference/gdata-overview.xml |    2 +-
 gdata/gdata-service.c             |    5 ++++-
 2 files changed, 5 insertions(+), 2 deletions(-)
---
diff --git a/docs/reference/gdata-overview.xml b/docs/reference/gdata-overview.xml
index eb274e3..3a97b0a 100644
--- a/docs/reference/gdata-overview.xml
+++ b/docs/reference/gdata-overview.xml
@@ -144,7 +144,7 @@
 				itself, rather than their application.</para>
 		</refsect2>
 
-		<refsect2>
+		<refsect2 id="cancellable-support">
 			<title>Cancellable Support</title>
 			<para>As libgdata is a network library, it has to be able to deal with operations which take a long (and indeterminate) amount
 				of time due to network latencies. As well as providing asynchronous operation support, every such operation in libgdata
diff --git a/gdata/gdata-service.c b/gdata/gdata-service.c
index a11ba29..738a8f4 100644
--- a/gdata/gdata-service.c
+++ b/gdata/gdata-service.c
@@ -1259,7 +1259,10 @@ _gdata_service_query (GDataService *self, const gchar *feed_uri, GDataQuery *que
  * Queries the service's @feed_uri feed to build a #GDataFeed.
  *
  * If @cancellable is not %NULL, then the operation can be cancelled by triggering the @cancellable object from another thread.
- * If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ * If the operation was cancelled before or during network activity, the error %G_IO_ERROR_CANCELLED will be returned. Cancellation has no effect
+ * after network activity has finished, however, and the query will return successfully (or return an error sent by the server) if it is first
+ * cancelled after network activity has finished. See the <link linkend="cancellable-support">overview of cancellation</link> for
+ * more details.
  *
  * A %GDATA_SERVICE_ERROR_PROTOCOL_ERROR will be returned if the server indicates there is a problem with the query, but subclasses may override
  * this and return their own errors. See their documentation for more details.