[grilo] core: updated grl_media_source_cancel() documentation

[Juan A. Suarez Romero <jasuarez src gnome org>]

commit 2ee06ab11b1db30bf41197603238436cf662f113
Author: Guillaume Emont <gemont igalia com>
Date:   Mon Feb 7 20:58:33 2011 +0100

    core: updated grl_media_source_cancel() documentation
    
    Signed-off-by: Juan A. Suarez Romero <jasuarez igalia com>

 src/grl-media-source.c |   13 ++++++++-----
 1 files changed, 8 insertions(+), 5 deletions(-)
---
diff --git a/src/grl-media-source.c b/src/grl-media-source.c
index 796404b..ecb2187 100644
--- a/src/grl-media-source.c
+++ b/src/grl-media-source.c
@@ -2062,15 +2062,18 @@ grl_media_source_supported_operations (GrlMetadataSource *metadata_source)
 /**
  * grl_media_source_cancel:
  * @source: a media source
- * @operation_id: the identifier of the running operation
+ * @operation_id: the identifier of the running operation, as returned by the
+ * function that started it
  *
  * Cancel a running method.
  *
- * Every method has a operation identifier, which is set as parameter in the
- * callback. The running operation can be cancel then.
+ * The derived class must implement the cancel vmethod in order to honour the
+ * request correctly. Otherwise, the operation will not be interrupted.
  *
- * The derived class must implement the cancel vmethod in order to
- * honor the request.
+ * In all cases, if this function is called on an ongoing operation, the
+ * corresponding callback will be called with the
+ * @GRL_CORE_ERROR_OPERATION_CANCELLED error set, and no more action will be
+ * taken for that operation after the said callback with error has been called.
  *
  * Since: 0.1.1
  */